Verbesserung
Top-Thema
Wichtig
Kleinigkeit
Wichtig
Für das Framework als gesamtes kann aktuell kein JavaDoc erzeugt werden, da das Ant-Tooling nur einzelne JavaDoc-Bäume für jedes Modul erzeugen kann und diese nicht verlinkt sind.
Verbesserung
- Tooling, um Gesamt-Dokumentation für das Framework erzeugen zu können.
- JavaDoc-Fehler bereinigen, so dass eine korrekte Verlinkung erzeugt werden kann: Siehe #24937.
- Sicherstellen, dass JavaDoc-Fehler im Build erkannt und bereinigt werden müssen.
- An Top-Logic-Features angepasste Dokumentation "Konfigurationsreferenz" für Config-Interfaces statt Methoden- und Konstanten-Liste
- Zusammen mit dem Code versionierte Dokumentation, direkt aus dem SVN anzeigbar - für jeden CWS aktuell.
- Durchsuchbare Dokumentation
Aktuelle Dokumentation: http://tl/svn/top-logic/trunk/TL/tl-doc/javadoc/index.html
Anwendung
Siehe JavaDoc.
Wunschliste
[ ] Bei der Anzeige von geerbten Properties einer Konfiguration kann der Typ Typ-Variablen enthalten, die im aktuellen Typ überhaupt nicht deklariert sind. In "Config (LayoutComponent)" das Property "class : Class<? extends T>" die Typ-Variable T stammt aus "PolymorphicConfiguration<T>", wobei T in LayoutComponent an "LayoutComponent" gebunden ist. [x] Geschachtelte Annotationen werden nicht angezeigt. http://tl/svn/top-logic/branches/CWS/CWS_24926/tl-doc/javadoc/index.html#com.top_logic.basic.util.AllocationService$Config#getReservedSpaceFactor() [x] Suche nach mehr als einem Search-Term "component filter" findet "VisibleComponentFilter" und "AbstractFilterComponent". [x] Suche nach komplettem Wort (explizit keine Teilwortsuche) mit Search-Term in Anführungszeichen. [ ] Suche nach seziellen Vorkommen "method:[Methoden-Name] return:[Typ-Name] doc:[Auftreten-im-Kommentar]" [ ] Type-Usage anzeigen + Erwähnungen in JavaDoc @link und @see bzw. danach suchen können. [x] Separate Links für Typ-Parameter erzeugen (PolymorphicConfiguration<LayoutComponent>), Separate Links für äußere Klassen (LayoutComponent.Config) [x] Tool-Tips für Link-Symbole (Stable Link und Source-Code Link) [ ] "abstract" wie eine Annotation anzeigen (unter der Deklaration) [ ] Methods: throws declarations anzeigen (wie eine Annotation unter der Deklaration) [ ] Option: Keine geerbten Properties bei Konfigurationen anzeigen. [ ] Option: Überschriebene Methoden in Klassen anzeigen. [ ] Bei überschriebenen Konfig-Properties die tatsächlichen Annotationen der Überschreibung anzeigen. Link auf die Definition. [ ] Referenzen auf Config-Properties nicht als Getter-Methoden darstellen sondern mit Property-Name. [ ] Abschnitte der Klassenbeschreibung auf- und zuklappen können. [ ] Suchergebnise auch mit der Maus anwählen können. [ ] Paketbaum soll nicht Anklicken eines Pakets auf- bzw. zuklappen - nur beim Klick auf den Expand-Button. [x] Fehler: Suffix der Signatur der referenzierten Methode taucht in der Beschreibung eines @see Tags auf: "UmlJS.createDiagramId(String,String): String)" in "Diagram" [x] Fehler: Beschreibungs-Sätze enden immer hat am ersten Punkt. Die Spezifikation sagt "This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag" [x] Konfigurationen: Alle Properties (auch die geerbten anzeigen) [x] Typ-Parameter anzeigen. [x] Suchindex für Inhalte [x] Suchfeld in allen Sichten anzeigen [x] Typ-Parameter in extends und implements anzeigen: "Extends GenericFunction" [x] Subtypes und Usage information aus abgeleiteten Modulen berücksichtigen. [x] Referenz auf den Source-Code im Trac funktioniert nur in tl-basic. [x] In Packages "inner", "outer" Package. "Package com.top_logic.<a>basic</a>.config.annotation" [x] Annotation Anzeige [x] Instances -> normale Configs [x] Package-Baum auf und zuklappen [x] Override: Do not show overridden methods, jump to the defining class, when a link to an overridden method is clicked. [x] Visibility [x] Keine Typ-Anzeige bei Enum-Constants. Fields - > Constants [x] Class PropertyKind -> Enum PropertyKind [x] Enum: Kein Extends [x] Annotations in eigene Category [x] Eigenes Template für Annotations, Methods -> Properties, kein implements. [x] Werte von Constanten anzeigen. [x] Category "Constants" [x] <xmp> in Kommentaren berücksichtigen (quoten) [ ] Wenn in einem Link auf eine nicht existierende Klasse verwiesen wird, sollte nicht für immer "Loading..." auf der Seite stehen. http://tl/svn/top-logic/trunk/TL/tl-doc/javadoc/index.html#com.top_logic.ClassDoesNotExists [ ] !JavaDoc für Tag-Libs: https://mvnrepository.com/artifact/taglibrarydoc/tlddoc [ ] Integration eines Spell-Checkers, damit das Kauderwelsch in der Dokumentation weniger wird: http://wiki.languagetool.org/java-api
Code-Migration
Aktivieren von JavaDoc für das Projekt
In den .build.properties des Projektes die Zeile löschen:
noJavaDoc=true
In den Projekt-Einstellungen JavaDoc Fehler als Fehler anzeigen lassen:
Bestehende kaputte JavaDoc-Links bereinigen.
Ant-Task javadoc im Projekt ausführen. Berichtete Warnungen so weit möglich korrigieren - insbesondere nicht wohlgeformtes XML.
Optional: Wenn nicht alle Fehler bereinigt werden können/wollen/sollen, kann eine JavaDoc-Baseline erzeugt werden (Fehler, die bekannt sind und im Build nicht berichtet werden sollen). Hierfür im Projekt das Ant-Target javadoc mit dem gesetzten Property javadoc.createBaseline=true einmalig ausführen. Die erzeugte Datein in /ext/javadoc/javadoc-ignores im Projekt mit einchecken.
Entwicklungsumgebung TL-Core
Um TL_trunk vollständig auszuchecken muss auch das Modul tl-buil_doclet ausgecheckt werden. Dieses benötigt eine externe Bibliothek aus dem JDK, die in Eclipse folgendermaßen einzurichten ist:
Test
Wenn man das Erkennen von JavaDoc-Fehlern im Build testen möchte, kann man in einer Java-Datei z.B. eine kauptte JavaDoc-Referenz einfügen und das Ant-Target javadoc im entsprechenden Modul ausführen. Dieses sollte dann als Fehler-Ausgabe auf die Konsole eine in Eclipse klickbare Meldung ausgeben, die zu dem Problem springt. Wenn man den Fehler eincheckt und ein CWS-Build laufen lässt, dann muss/wird dieser Fehler im Build-Status berichtet.