Enhancement
No JavaDoc can currently be generated for the framework as a whole, as the Ant tooling can only generate individual JavaDoc trees for each module and these are not linked.
Improvement
- Tooling to be able to generate complete documentation for the framework.
- Clean up JavaDoc errors so that a correct link can be generated: See #24937.
- Ensure that JavaDoc errors must be recognized and cleaned up in the build.
- Documentation adapted to top logic features "Configuration reference" for config interfaces instead of method and constant list
- Documentation versioned together with the code, can be displayed directly from the SVN - up-to-date for every CWS.
- Searchable documentation
Current documentation: http://tl/svn/top-logic/trunk/TL/tl-doc/javadoc/index.html
Application
See JavaDoc.
Wish list
[ ] When displaying inherited properties of a configuration, the type may contain type variables that are not declared at all in the current type. In "Config (LayoutComponent)" the property "class : Class<? extends T>" the type variable T originates from "PolymorphicConfiguration<T>", whereby T in LayoutComponent is bound to "LayoutComponent". [x] Nested annotations are not displayed. http://tl/svn/top-logic/branches/CWS/CWS_24926/tl-doc/javadoc/index.html#com.top_logic.basic.util.AllocationService$Config#getReservedSpaceFactor() [x] Search for more than one search term "component filter" finds "VisibleComponentFilter" and "AbstractFilterComponent". [x] Search for complete word (explicitly no partial word search) with search term in quotation marks. [ ] Search for specific occurrences "method:[method-name] return:[type-name] doc:[occurrence-in-comment]" [ ] Display type-usage + mentions in JavaDoc @link and @see or be able to search for them [x] Create separate links for type parameters (PolymorphicConfiguration<LayoutComponent>), separate links for outer classes (LayoutComponent.Config) [x] Tool tips for link symbols (Stable Link and Source-Code Link) [ ] Show "abstract" like an annotation (below the declaration) [ ] Methods: throws declarations (like an annotation below the declaration) [ ] Option: Do not show inherited properties for configurations [ ] Option: Show overridden methods in classes [ ] For overridden config properties, show the actual annotations of the override. Link to the definition. [ ] Display references to config properties not as getter methods but with property name. [ ] Expand and collapse sections of the class description. [ ] Select search results with the mouse. [ ] Package tree should not expand or collapse when clicking on a package - only when clicking on the expand button. [x] Error: Suffix of the signature of the referenced method appears in the description of an @see tag: "UmlJS.createDiagramId(String,String): String)" in "Diagram" [x] Error: Description sentences always end at the first dot. The specification says "This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag" [x] Configurations: Show all properties (including inherited ones) [x] Show type parameters [x] Search index for content [x] Show search field in all views [x] Show type parameters in extends and implements: "Extends GenericFunction" [x] Consider subtypes and usage information from derived modules [x] Reference to source code in trac only works in tl-basic [x] In packages "inner", "outer" package. "Package com.top_logic.<a>basic</a>.config.annotation" [x] Annotation display [x] Instances -> normal Configs [x] Expand and collapse package tree [x] Override: Do not show overridden methods, jump to the defining class, when a link to an overridden method is clicked [x] Visibility [x] No type display for enum constants. Fields - > Constants [x] Class PropertyKind -> Enum PropertyKind [x] Enum: No Extends [x] Annotations in own category [x] Own template for annotations, Methods -> Properties, no implements [x] Show values of constants [x] Category "Constants" [x] Consider <xmp> in comments (quote) [ ] If a link refers to a non-existent class, "Loading...." on the page forever. http://tl/svn/top-logic/trunk/TL/tl-doc/javadoc/index.html#com.top_logic.ClassDoesNotExists [ ] !JavaDoc for tag libs: https://mvnrepository.com/artifact/taglibrarydoc/tlddoc [ ] Integration of a spell checker to reduce gibberish in the documentation: http://wiki.languagetool.org/java-api
Code migration
Activating JavaDoc for the project
Delete the line in the .build.properties of the project:
noJavaDoc=true
Display JavaDoc errors as errors in the project settings:
Clean up existing broken JavaDoc links.
Execute Ant task javadoc in the project. Correct reported warnings as far as possible - especially XML that is not well-formed.
Optional: If not all errors can/want/should be cleaned up, a JavaDoc baseline can be created (errors that are known and should not be reported in the build). To do this, execute the Ant target javadoc once in the project with the property javadoc.createBaseline=true set. Check in the generated files in /ext/javadoc/javadoc-ignores in the project.
TL-Core development environment
To check out TL_trunk completely, the tl-buil_doclet module must also be checked out. This requires an external library from the JDK, which must be set up in Eclipse as follows:
Test
If you want to test the recognition of JavaDoc errors in the build, you can, for example, insert a complete JavaDoc reference in a Java file and execute the Ant target javadoc in the corresponding module. This should then output an error message to the console that can be clicked in Eclipse and jumps to the problem. If you check in the error and run a CWS build, then this error must/will be reported in the build status.