Heiner KückerJspDoc |
|||||||||||||||||||
|
Home Java-Seite Bit Packed Array ASM Improved heterogene Map, HMap Constraint Code Generator JSP WorkFlow PageFlow FlowControl Page Flow Engine Web Flow Engine Control_and_Command JSP_Spreadsheet Code-Generator für Option-Either-Stil in Java verbesserter Comparator Fluent-Interface Code-Generator auf Basis einer Grammatik Visitor mit Multidispatch for-Schleife mit yield-return Kognitions-Maschine semantisches Netz Domain Parser Codegenerator_für hierarchische Datenstrukturen Expression_Engine Formula_Parser Thread Preprocessor State Transition Engine AspectJ Java_Explorer DBF_Library Kalender_Applet SetGetGen BeanSetGet CheckPackage LineNumbers GradDms Excel-Export StringTokenizer JspDoc JspCheck JSP-Schulung Java Server Pages Struts Ascii-Tabellen- Layouter Ascii-Baum- Layouter Ascii-Art-Fluss- Diagramm- Parser AsciiArt AssignmentMatrix Layouter StringSerial Silbentrennung JDBC_Schlüssel- Generierung bidirektional/ unidirektional gelinkte Liste Java_Sitemap Generator XmlBuilder RangeMap StringFormatter VersionSafe XCopy JTextField CommandLine- ParamReader Bitmap-Grafik MultiMarkable- Buffered- InputStream JavaCache JdomUtil CollectionUtil XML Really Pull Parser Log-Filter Remote-Protokoll Sudoku-Generator Delegation statt Mehrfachvererbung Disjunct Interval Set WebCam_Demo Weiterentwicklung_Java Alaska-XBase++-Seite Projekte Philosophien Techniken Konzepte Sudoku Kontakt / Impressum Links SiteMap Letzte Aktualisierung: 23.01.2003 |
JspDoc
Tool zum Erzeugen von javadoc-Dokumentationen für Java Server Pages. javadoc ist der Standard für die Dokumentation von Java-Programmen. Es bietet einen einheitlichen Rahmen für die Dokumentation von Source-Files und erzeugt Dokumentationen im HTML-Format mit Verzeichnissen, Hyperlinks, Vererbungsbäumen und Indizes in gutaussehender und leistungsfähiger Form. Leider sind JSP-Dateien bei der Dokumentation über javadoc aussen vor. Das hier vorgestellte kleine Tool ermöglicht die Anwendung des javadoc-Tools auch auf die für Web-Applikationen wichtigen JSP-Dateien. Die Arbeitsweise von jspdocJspdoc durchläuft das per Parameter übergebene JSP-Verzeichnis rekursiv und parst die JSP-Dateien ein.In den JSP-Dateien sucht jspdoc nach der javadoc-Startsequenz /**Der hier folgende Block wird bis zum endenden */eingelesen. Dies setzt voraus, dass die reservierten Sequenzen nicht im HTML-Code benutzt werden. Sonst wäre ein wesentlich aufwändigerer Parser notwendig. Ich habe zwar im Verlaufe meiner Programmiertätigkeit das Reservieren von Zeichen für einen speziellen Zweck (Escape-Sequenzierung) als Quelle allen Übels identifiziert, aber an dieser Stelle ist es wahrscheinlich in Ordnung. Als Platzhalter für die JSP-Datei wird im per Parameter übergebenen Source-Verzeichnis eine entsprechende Java-Datei mitsamt Sub-Pfad angelegt. Als Klassen-Name wird der Name der JSP-Datei verwendet. Das Package entspricht dem Pfad der JSP-Datei. Der Einbau von javadoc-Kommentaren in JSP´s soll aber nicht dem Zupflastern der JSP´s mit Code Vorschub leisten. JSP´s dienen als View; Code zur HTML-Generierung sollte in Custom-Tag-Librarys untergebracht werden und funktionaler Code gehört in Servlets oder like Struts in Action-Methoden. Weitere DateienIm Webordner gibt es ausser den JSP´s noch weitere Dateien:css - Cascading Style Sheets js - Java Script gif - Grafiken jpgEs kann wünschenswert sein, auch Kommentare zu diesen Dateien mitzuführen. Dafür kann in den jeweiligen Verzeichnissen jeweils eine Datei files.jspdochinterlegt werden. Diese Datei enthält entsprechende Kommentare im bekannten Properties-File-Format larr.gif = GIF-Grafik Pfeil links, left arrow rarr.gif = GIF-Grafik Pfeil rechts, right arrowDa der Kommentar auf eine Zeile beschränkt ist, wird als Ersatz für den Zeilenumbruch \n verwendet. Für die Package-Übersichtsdokumentation sind in javadoc die Dateien package.html vorgesehen. jspdoc verwendet dafür die Dateien package.jspdoc. Sie werden unter dem Namen package.html in die Source-Verzeichnisse kopiert. Beim Zusammenbau einer Web-Applikation zu einem war-File sollten die Dateien files.jspdoc und package.jspdoc ausgeschlossen werden. Konfigurations-ParameterAls Startparameter sind nötig:-JSP-Verzeichnis -Ziel-Verzeichnis in welches die temporären Java-Quell-Klassen abgelegt werden -Package für die generierten java-FilesIm Zielverzeichnis wird ein weiterer dem Package entsprechender Unterpfad angelegt. Hier ein Beispiel: -Ziel-Verzeichnis G:\javaprog\src -Package de.javaprog.JSP -JSP-Datei web\purchase\purchaseitem.jspDaraus entsteht der engültige Pfad: G:\javaprog\src\de\javaprog\JSP\purchase\purchaseitemmit dem Package: de.javaprog.JSP.purchase ProblemeDie Namen der erzeugten Java-Klassen müssen die Restriktionen für Java- Identifier erfüllen:
Einbindung in ANTDer Aufruf von jspdoc wird in das javadoc-Target gelegt. Ein Target ist eine auszuführende Aufgabe, die aus mehreren Kommandos, in ANT heissen die Kommandos Tasks, besteht. Am einfachsten ist ein Target mit einer Prozedur vergleichbar. In ANT ist es über den Build-In-Task <java> möglich, Java-Programme zu starten. Darüber wird jspdoc ein- oder mehrmals gestartet um die temporären Klassen zu erzeugen. Danach wird der javadoc-Task aufgerufen. Nach dem Erzeugen der javadoc-HTML- Files werden die temporären Klassen mit allen dazugehörenden Verzeichnissen gelöscht. Im aufgelisteten Beispiel wird die javadoc-Generierung im Sinne einer Script-Strukturierung in ein javadoc-Target und ein init-Target aufgeteilt.
<!-- =================================================================== -->
<!-- Initialization target -->
<!-- =================================================================== -->
<target name="init">
<!-- JspDoc parameters -->
<property name="jspdocprog.dir" value="../jspdocprog"/>
<property name="jsp.dir" value="./web"/>
<property name="jspdocetc.dir" value="./etc"/>
<property name="jspdocdest.dir" value="./src"/>
<property name="jspdoc.package" value="de.jspdoctest.JSP"/>
<property name="jspdocetc.package" value="de.jspdoctest.etc"/>
<property name="jspdoc.tempdir" value="${jspdocdest.dir}\de\jspdoctest"/>
</target>
<!-- =================================================================== -->
<!-- Creates the API documentation -->
<!-- =================================================================== -->
<target name="javadoc" depends="init">
<delete dir="${jspdoc.tempdir}"/> <!-- temporaere java-Files loeschen -->
<!-- Aufruf jspdoc fuer JSP-Dateien -->
<echo message="*********** JspDoc ${jsp.dir} ***********"/>
<java classname="JspDoc" fork="true" failonerror="true">
<classpath>
<pathelement path="${jspdocprog.dir}"/>
</classpath>
<arg value="${jsp.dir}"/>
<arg value="${jspdocdest.dir}"/>
<arg value="${jspdoc.package}"/>
</java>
<!-- Aufruf jspdoc fuer etc-Dateien -->
<echo message="*********** JspDoc ${etc.dir} ***********"/>
<java classname="JspDoc" fork="true" failonerror="true">
<classpath>
<pathelement path="${jspdocprog.dir}"/>
</classpath>
<arg value="${jspdocetc.dir}"/>
<arg value="${jspdocdest.dir}"/>
<arg value="${jspdocetc.package}"/>
</java>
<mkdir dir="${build.javadocs}"/>
<javadoc packagenames="${packages}"
classpath="${classpath}"
sourcepath="${build.src}"
destdir="${build.javadocs}"
author="true"
version="true"
use="true"
splitindex="true"
noindex="false"
windowtitle="${apptitle} API"
doctitle="${apptitle}"
bottom="Heiner Kuecker www.heiner-kuecker.de"
/>
<delete dir="${jspdoc.tempdir}"/> <!-- temporaere java-Files loeschen -->
</target>
Download der Quelldateien jspdoc.zip Mitgelieferte Dateien: jspdoc.zip enthält eine für JSP-Web-Applikationen typische Verzeichnis-Struktur:
Installation: Entpacken in Verzeichnis Ihrer Wahl (z.B. G:\jspdoc) Start mit build.bat im Verzeichnis /jspdoc/jspdoctest Andere ähnliche ToolsEs gibt noch einige vergleichbare Tools. Eine Suche auf Google hilft hier weiter:Google-Suche nach jspdoc
Achtung: Erweiterungen und Fixes stelle ich ohne Historie
und ohne Ankündigung hier bereit. Lizenzbedingungen:
Die Programme, Quelltexte und Dokumentationen können ohne
irgendwelche Bedingungen kostenlos verwendet werden. |
||||||||||||||||||