<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\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 &amp; Aufnahme ins Inhaltsverzeichnis \\ \hline
	\code{toc0}  &amp; keine Stufe \\
	\code{toc1}  &amp; oberste Stufe \code{Default}-Wert \\
	\code{toc2}  &amp; obersten zwei Stufen\\
	\code{toc3}  &amp; alle Stufen \\
	\code{toc}   &amp; entspricht \code{toc3} \\
	\code{notoc} &amp; 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		  &amp; author \\
		 method		  &amp; category \\
		 constr		  &amp; deprecated \\
		  &amp; parameter \\		 
		 fullname		  &amp; see \\
		 package		  &amp; serial \\
		 inherits		  &amp; serialData \\
		 implements		  &amp; serialField \\
		 outerclass		  &amp; since \\
		  &amp; return \\
		 elementname &amp; throws \\
		 inheritOf &amp; version \\
		 inheritancetable &amp;
		\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 &amp; \begin{sideways}jdclassheader\end{sideways} &amp; \begin{sideways}jdfield\end{sideways} &amp; \begin{sideways}jdconstructor\end{sideways} &amp; \begin{sideways}jdmethod\end{sideways} \\
		\hline	
			\befehl{jdpublic}	&amp; X &amp; X &amp; X &amp; X 
		\\ \hline
			\befehl{jdprotected} &amp; X &amp; X &amp; X &amp; X
		\\ \hline
			\befehl{jdprivate} 	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{jdstatic}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{jdabstract}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{jdfinal}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
			\befehl{jdtransient}	&amp; &amp; X &amp;  &amp; 
		\\ \hline
		 \befehl{jdvolatile}	&amp;  &amp; X &amp; &amp; 
		\\ \hline
		 \befehl{jdpackage\{packagename\}} 	&amp; X &amp;  &amp;  &amp; 
		\\ \hline
		 \befehl{jdinherits\{classname\}}	&amp; X &amp;  &amp;  &amp; 
		\\ \hline
		 \befehl{jdimplements\{interface\}}	&amp; X &amp;  &amp;  &amp; 
		\\ \hline
		 \befehl{jdouterclass\{classname\}}	&amp; X &amp;  &amp;  &amp; 
		\\ \hline
		 \befehl{jdtype\{type\}}	&amp;  &amp; X &amp;  &amp; X
		\\ \hline
		 \befehl{JDauthor\{beschreibung\}}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{JDcategory\{beschreibung\}}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{JDdeprecated\{beschreibung\}}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{JDsee\{beschreibung\}}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{JDserial\{beschreibung\}}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{JDserialData\{beschreibung\}}	&amp;  &amp;  &amp; X &amp; X
		\\ \hline
		 \befehl{JDserialField\{beschreibung\}}	&amp;  &amp; X &amp;  &amp; 
		\\ \hline
		 \befehl{JDsince\{beschreibung\}}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{JDtext\{beschreibung\}}	&amp; X &amp; X &amp; X &amp; X
		\\ \hline
		 \befehl{JDversion\{beschreibung\}}	&amp; X &amp; &amp;  &amp; 
		\\ \hline
		 \befehl{JDreturn\{beschreibung\}}	&amp;  &amp;  &amp; X &amp; X
		\\ \hline
		 \befehl{JDpara\{datentyp\}\{name\}\{beschreibung\}} 	&amp; &amp; &amp; X &amp; X
		\\ \hline
		 \befehl{JDthrows\{exceptionname\}\{beschreibung\}} &amp;  &amp;  &amp; X &amp; X
	\end{tabular}
	\caption{Verwendung von Befehlen in Umgebungen}
	\label{tab:befehleInUmgebung}
	\end{center}
\end{table}

\end{document}</pre></body></html>