Currently, no JavaDoc can be generated for the framework as a whole, because the Ant tooling can only generate individual JavaDoc trees for each module and these are not linked.
Improvement
- Tooling to be able to generate overall documentation for the framework.
- Clean up JavaDoc errors so that proper linking can be generated: See #24937.
- Ensure JavaDoc errors must be detected 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 along with the code, viewable directly from SVN - up to date for each 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 comes from "PolymorphicConfiguration<T>", where T is bound to "LayoutComponent" in 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 quotes. [ ] Search for specific occurrences "method:[method-name] return:[type-name] doc:[occurrence-in-comment]" [ ] Show type-usage + mentions in JavaDoc @link and @see or be able to search for it. [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 (under the declaration) [ ] Methods: show throws declarations (like an annotation under the declaration) [ ] Option: show no 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 a package - only when clicking the expand button. [x] Error: Suffix of the referenced method's signature appears in the description of an @see tag: "UmlJS.createDiagramId(String,String): String)" in "Diagram" [x] Error: description sentences always has end at 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] Show search index for contents [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 works only 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-existing class, it should not always say "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 [ ] Integrate a spell checker to reduce gibberish in documentation: http://wiki.languagetool.org/java-api
Code migration
Enable JavaDoc for the project
In the .build.properties of the project delete the line:
noJavaDoc=true
In the project settings, show JavaDoc errors as errors:
Clean up existing broken JavaDoc links.
Run Ant task javadoc in the project. Correct reported warnings as much as possible - especially XML that is not well-formed.
Optional: If not all errors can/want/want to 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 created files in /ext/javadoc/javadoc-ignores in the project.
Development environment TL-Core
To fully check out TL_trunk the module tl-buil_doclet must also be checked out. This requires an external library from the JDK, which has to be set up in Eclipse as follows:
Test
If you want to test the detection of JavaDoc errors in the build, you can e.g. insert a main JavaDoc reference in a Java file and execute the Ant target javadoc in the corresponding module. This should then output as error output to the console a message clickable in Eclipse that 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.