Verbesserung
Top-Thema
Wichtig
Kleinigkeit
Wichtig
Verbesserung
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.