summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/javadoc/doc/javadoc_doc_de.tex
blob: db8e8a58cd1f20291de221daaa4817347c8d1d8d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
\documentclass[11pt,a4paper]{article}
\usepackage[ngerman]{babel}
\usepackage[T1]{fontenc}
\usepackage[ansinew]{inputenc}
\usepackage{csquotes}
\usepackage{rotating}

\newcommand{\code}[1]{\protect\texttt{#1}}
\newcommand{\befehl}[1]{\code{$\backslash$#1}}

\begin{document}
\title{Das \code{javadoc} Package}
\author{Jolle\footnote{Verbesserungsvorschläge, Kommentare, Korrekturen, Anregungen und Danksagungen an \mbox{joerman.lieder@gmx.net}}  }
\date{\today}
\maketitle

\begin{abstract}
Das \code{javadoc} Package bietet eine einfache Möglichkeit, Dokumentationen von Quellcode zu erstellen. Es leitet sich vom Dokumentationssystem javadoc für Java ab und bietet dieselben Attribute an. Aber natürlich kann auch Quellcode anderer Sprachen damit dokumentiert werden. Das Paket steht unter GNU GENERAL PUBLIC LICENSE\footnote{www.gnu.org}
\end{abstract}

\tableofcontents

\section{Einführung}
Mit dem Programm \code{javadoc} wird den Programmierern in der Java-Welt ein mächtiges Werkzeug gegeben, ihren Quellcode zu dokumentieren. Javadoc arbeitet mit besonders formatierten Kommentaren im Quelltext und generiert daraus eine umfassende Sammlung an HTML-Seiten. Das Package \code{javadoc} bietet die Möglichkeit, mit denselben Attributen eine Dokumentation mit \LaTeX{} zu erstellen. Mächtig wird das Package vor allem im Zusammenspiel mit einem Doclet, das die Kommentare aus dem Quellcode in \TeX-Dateien mit den Befehlen dieses \code{javadoc}-Packages umwandelt.

\section{Optionen und benötigte Packages}
Derzeit benötigt \code{javadoc} nur ein Paket, nämlich \code{longtable}. Ohne dieses kann die z.T. sehr umfangreiche Tabelle mit geerbten Feldern und Methoden nicht dargestellt werden.

Das Paket bietet Optionen, um das Layout und die Struktur der Dokumentation anzupassen. Das Paket selbst belegt 3 Hierarchiestufen, durch die Optionen \code{chapter}, \code{section}, \code{subsection} lässt sich die oberste Stufe festlegen, die hinteren werden automatisch nach unten geschoben. Wird keine Option angegeben, wird \code{section} als oberste Stufe verwendet. Die zweite Möglichkeit über Optionen das Verhalten zu beeinflussen, liegt im Festlegen, welche Hierarchiestufe ins Inhaltsverzeichnis mit aufgenommen wird und welche nicht. Dies wird realisiert durch die *-Befehle von \code{chapter} usw. Die folgende Tabelle listet die möglichen Optionen auf.

\begin{center}
	\begin{tabular}{l|l}
	Option & Aufnahme ins Inhaltsverzeichnis \\ \hline
	\code{toc0}  & keine Stufe \\
	\code{toc1}  & oberste Stufe \code{Default}-Wert \\
	\code{toc2}  & obersten zwei Stufen\\
	\code{toc3}  & alle Stufen \\
	\code{toc}   & entspricht \code{toc3} \\
	\code{notoc} & entspricht \code{toc0}
	\end{tabular}
\end{center}

Unabhängig davon, welche Option angegeben ist, können andere Einstellungen die Darstellung im Inhaltsverzeichnis verändern.

Die \code{hyperref}-Option kann angegeben werden, wenn erwünscht ist, dass innerhalb der Ausgabedatei Verlinkungen erzeugt werden. So lassen sich von Parametertypen oder Rückgabewerten oder Vererberklassennamen mit Mausklick die entsprechenden Klassen aufrufen, wenn sie denn in derselben Datei liegen. Ansonsten springt Acrobat an den Anfang des Dokuments. Diese Option empfiehlt sich erst am Ende des Schreibvorgangs zu verwenden, da sie sehr viele Warnungen aufgrund nicht verfolgbarer Referenzen erzeugt. Wird diese Option gewählt wird das Package \code{hyperref} ohne eine Option eingebunden. Diese können mit \befehl{hypersetup} nachgeladen werden.

Desweiteren bietet das \code{javadoc}-Package Möglichkeiten, die Ausgaben zwischen verschiedenen Sprachen umzustellen. Das betrifft aber nur Überschriften und Beschreibungen, natürlich nicht codespezifische Wörter. Außerdem werden keine sprachspezifischen Einstellungen durchgeführt, sondern nur Übersetzungen getätigt. Als derzeit einzige Option lässt sich \code{deutsch} auswählen, Standard ist Englisch. Um andere Sprachen zu implementieren brauchen nur die Befehle überschrieben werden. Alle Sprachbefehle beginnen mit \befehl{jd@lang@}, die jeweiligen Endungen sind in Tabelle \ref{tab:jd:lang} gelistet.

\begin{table}
	\begin{center}
	\begin{tabular}[h]{l|l}
		 field		  & author \\
		 method		  & category \\
		 constr		  & deprecated \\
		  & parameter \\		 
		 fullname		  & see \\
		 package		  & serial \\
		 inherits		  & serialData \\
		 implements		  & serialField \\
		 outerclass		  & since \\
		  & return \\
		 elementname & throws \\
		 inheritOf & version \\
		 inheritancetable &
		\end{tabular}
		\end{center}
	\label{tab:jd:lang}
	\caption{Sprachbefehle}
\end{table}

\section{Befehle zur Darstellung}
Bevor wir auf die Umgebungen und die Dokumentationsmöglichkeiten zu Sprechen kommen, sollten noch 2 Befehle genannt werden, die der Gestaltung dienen.
\befehl{jdinh} steht für \enquote{Inherits} und malt einen Vererbungspfeil von rechts nach links. \befehl{jdcode} benötigt einen Parameter und stellt diesen Text in TrueType-Schrift dar.

\section{Verlinkung im PDF}
Um Verlinkungen innerhalb des PDFs zu erzeugen, muss beim Argument von \befehl{jdtype} und beim jeweils 1. Argument von \befehl{JDpara} und \befehl{jdInhEntry} die entsprechenden Wörter über die Befehle \befehl{jdtypesimple\{type\}} oder \befehl{jdtypearray\{name\}\{dimension\}} oder \befehl{jdtypegeneric\{name\}\{generisch\}} als Klassen gekennzeichnet werden. Im generischen Typ müssen die einzelnen Klassen wieder mit den oben genannten Befehlen gekennzeichnet werden. Die Ziele dieser Verlinkungen werden automatisch gesetzt. Wird die \code{hyperref}-Option nicht genutzt, können die Befehle trotzdem angegeben werden. Sie erzeugen dann keinen Fehler.

\section{Known Issues}
\begin{itemize}
	\item Probleme bereiten derzeit die nicht existierenden Verlinkungsziele von Datentypen, deren Klassen nicht beschrieben werden. Diese tauchen dann als Warnungen beim Kompilieren und als Verweise ins Nichts im PDF auf. 
	\item Auch werden außer Datentypen keine anderen Sachen (wie Methoden) verlinkt.
	\item Beim Verlinken wird nur der Klassenname verwendet, nicht das Package, sodass zwei gleiche Klassen in unterschiedlichen Paketen das gleiche Ziel darstellen. Gelöst werden kann es dadurch, das der volle Name der Klasse angegeben wird. Das Doclet unterstützt derzeit keine generischen Typen und \enquote{doppelte} Klassennamen. Weitere Informationen zum Doclet finden sich in der dortigen Dokumentation.
	\item Methoden- und Feldnamen erzeugen häufig zu volle Boxen in den Überschriften.
\end{itemize}

\section{Gliederung einer Klasse}
Die Hierarchie-Stufen wurden schon mehrfach erwähnt, nun soll erläutert werden, was sie bedeuten. Um eine Klasse zu beschreiben wird der Klassenname als Hauptüberschrift verwendet (oberste Stufe). Danach folgen Unterteilungen für Felder, Konstruktoren oder Methoden. Und auf der untersten Ebene stehen die Namen der einzelnen Elemente einer Klasse.

\section{Beschreiben einer Klasse}
Als äußere Umgebung für eine Klasse wird \code{jdclass} verwendet. \code{jdclass} hat ein Pflichtargument, dass den Namen der Klasse beschreibt. Als optionales Argument lässt sich \code{class} oder \code{interface} angeben, wobei standardmäßig ersteres verwendet wird. Auch \code{enum} wäre ein denkbarer Wert. Innerhalb der Klassendeklaration lassen sich die unterschiedlichen Elemente beschreiben. Dabei ist die folgende Reihenfolge notwendig.

\begin{itemize}
	\item \code{jdclassheader}
	\item \code{jdinheritancetable}
	\item \code{jdfield}
	\item \code{jdconstructor}
	\item \code{jdmethod}
\end{itemize}

Die Umgebung \code{jdclassheader} darf nur einmal pro Klasse vorkommen, die Umgebungen \code{jdconstructor} und \code{jdinheritancetable} benötigen kein Pflichtargument mit dem Namen.

\subsection{Die Umgebung \protect\code{jdinheritancetable}}
In dieser Tabelle werden mit \befehl{jdInhEntry} die Einträge für die Tabelle erzeugt. Der Befehl braucht 2 Argumente, das 1. für ein Element, das 2. für die Klasse, von der das Element geerbt wird.

\subsection{Befehle für alle Umgebungen außer \protect\code{jdinheritancetable}}
Für jede dieser Umgebungen sind im Allgemeinen die gleichen Elemente gültig. Allerdings werden nicht alle Elemente überall verwendet. In Tabelle \ref{tab:befehleInUmgebung} ist aufgeführt, welche Befehle in welcher Umgebung verwendet werden. Die Verwendung von Befehlen, die nicht zur Umgebung gehören, erzeugt keinen Fehler, hat aber keine Auswirkung. Darüberhinaus unternimmt das \code{javadoc}-Package auch keine Java-Syntaxprüfung. So ist es durchaus möglich, sich widersprechende Modifier anzugeben, aber nicht sinnvoll.

\subsubsection{Modifier}
Folgende Modifier lassen sich zu einem Element angeben, sie verlangen keine Argumente.
\begin{itemize}
	\item \befehl{jdpublic}
	\item \befehl{jdprotected}
	\item \befehl{jdprivate}
	\item \befehl{jdstatic}
	\item \befehl{jdabstract}
	\item \befehl{jdfinal}
	\item \befehl{jdtransient}
	\item \befehl{jdvolatile}
\end{itemize}

\subsubsection{Codebasierte Attribute}
Folgende Befehle sind keine typischen Javadoc-Elemente, enthalten aber wertvolle Informationen zu einer Klasse.

\begin{itemize}
	\item \befehl{jdpackage\{packagename\}} Das Package, in dem die Klasse enthalten ist.
	\item \befehl{jdinherits\{classname\}} Vererbte Klasse. Um eine Vererbungshierarchie darzustellen, kann der Pfeil \befehl{jdinh} verwendet werden.
	\item \befehl{jdimplements\{interface\}} Ein Interface, dass implementiert wird. Kann mehrfach vorkommen.
	\item \befehl{jdouterclass\{classname\}} Definiert für innere Klassen den Namen der äußeren.
	\item \befehl{jdtype\{type\}} Datentyp, vor allem bei Rückgabewerten oder Feldnamen. Wird bei einer Methode kein Rückgabewert angegeben, gilt automatisch \code{void}.
\end{itemize}

\subsubsection{Javadocbasierte Attribute}
Die meisten Javadoc-Attribute haben ein Pflichtargument, dass ihre Beschreibung enthält. Dazu zählen folgende Attribute: 

\begin{itemize}
	\item \befehl{JDcategory\{beschreibung\}}
	\item \befehl{JDdeprecated\{beschreibung\}}
	\item \befehl{JDserial\{beschreibung\}}
	\item \befehl{JDserialData\{beschreibung\}}
	\item \befehl{JDserialField\{beschreibung\}}
	\item \befehl{JDsince\{beschreibung\}}
	\item \befehl{JDtext\{beschreibung\}}
	\item \befehl{JDversion\{beschreibung\}}
	\item \befehl{JDreturn\{beschreibung\}}
\end{itemize}

Darüberhinaus gibt es drei weitere Javadoc-Attribute, die mehrfach auftreten dürfen und z.T. mehrere Argumente annehmen.
\begin{itemize}
	\item \befehl{JDsee\{beschreibung\}}
	\item \befehl{JDauthor\{autorname\}}
	\item \befehl{JDpara\{datentyp\}\{name\}\{beschreibung\}}
	\item \befehl{JDthrows\{exceptionname\}\{beschreibung\}}
\end{itemize}

\subsection{Zuordnungstabelle Umgebung zu Befehl}
Die Tabelle \ref{tab:befehleInUmgebung} fasst zusammen, welche beschreibenden Befehle in welcher Umgebung auftauchen dürfen.

\begin{table}[!ht]
	\begin{center}
	\begin{tabular}{l|c|c|c|c }
		Befehl & \begin{sideways}jdclassheader\end{sideways} & \begin{sideways}jdfield\end{sideways} & \begin{sideways}jdconstructor\end{sideways} & \begin{sideways}jdmethod\end{sideways} \\
		\hline	
			\befehl{jdpublic}	& X & X & X & X 
		\\ \hline
			\befehl{jdprotected} & X & X & X & X
		\\ \hline
			\befehl{jdprivate} 	& X & X & X & X
		\\ \hline
		 \befehl{jdstatic}	& X & X & X & X
		\\ \hline
		 \befehl{jdabstract}	& X & X & X & X
		\\ \hline
		 \befehl{jdfinal}	& X & X & X & X
		\\ \hline
			\befehl{jdtransient}	& & X &  & 
		\\ \hline
		 \befehl{jdvolatile}	&  & X & & 
		\\ \hline
		 \befehl{jdpackage\{packagename\}} 	& X &  &  & 
		\\ \hline
		 \befehl{jdinherits\{classname\}}	& X &  &  & 
		\\ \hline
		 \befehl{jdimplements\{interface\}}	& X &  &  & 
		\\ \hline
		 \befehl{jdouterclass\{classname\}}	& X &  &  & 
		\\ \hline
		 \befehl{jdtype\{type\}}	&  & X &  & X
		\\ \hline
		 \befehl{JDauthor\{beschreibung\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDcategory\{beschreibung\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDdeprecated\{beschreibung\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDsee\{beschreibung\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDserial\{beschreibung\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDserialData\{beschreibung\}}	&  &  & X & X
		\\ \hline
		 \befehl{JDserialField\{beschreibung\}}	&  & X &  & 
		\\ \hline
		 \befehl{JDsince\{beschreibung\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDtext\{beschreibung\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDversion\{beschreibung\}}	& X & &  & 
		\\ \hline
		 \befehl{JDreturn\{beschreibung\}}	&  &  & X & X
		\\ \hline
		 \befehl{JDpara\{datentyp\}\{name\}\{beschreibung\}} 	& & & X & X
		\\ \hline
		 \befehl{JDthrows\{exceptionname\}\{beschreibung\}} &  &  & X & X
	\end{tabular}
	\caption{Verwendung von Befehlen in Umgebungen}
	\label{tab:befehleInUmgebung}
	\end{center}
\end{table}

\end{document}