summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/javadoc/doc/javadoc_doc_en.tex
blob: d038fbe7cc48281c623c10975b943faf73a95498 (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
\documentclass[11pt,a4paper]{article}
\usepackage[english]{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{The \code{javadoc} Package}
\author{Jolle\footnote{Comments, Help, Questions, Hints, Critics to \mbox{joerman.lieder@gmx.net}}  }
\date{\today}
\maketitle

\begin{abstract}
The \code{javadoc} package provides an easy way to document source code. It is related to the javadoc system for java source code and tries to provide the same descriptions. But, of course, source code of other languages can be documented using this package. The package is under GNU GENERAL PUBLIC LICENSE\footnote{www.gnu.org}
\end{abstract}

\tableofcontents

\section{Introduction}
Javadoc is a powerful tool for java developer to document their source code. It produces a comprehensive collection of HTML-pages out of special formattet comments in sourc code. The package \code{javadoc} uses the same attributes to describe the source code with \LaTeX{}. In combination with the TexGen doclet the \TeX-documentation can be generated with the javadoc out of the source code.

\section{Options and Required Packages}
The \code{javadoc}-package requires one other package. The \code{longtable} is used to display the tables of inherited fields and methods.

The package provides options to customize the layout and structure of the document. The package occupies 3 levels of hierarchy, with the options \code{chapter}, \code{section}, \code{subsection} the highest level can be set, the others will be adapt automatically. The default is \code{section}. The second possibility to customize the behaviour is to set the table of content. The two forms of \code{chapter} and \code{chapter*} and so on can be used. The following table lists the possible options.

\begin{center}
	\begin{tabular}{l|l}
	Option & Table of Content \\ \hline
	\code{toc0}  & no level \\
	\code{toc1}  & highest level, default \\
	\code{toc2}  & the two highest levels\\
	\code{toc3}  & all levels \\
	\code{toc}   & like \code{toc3} \\
	\code{notoc} & like \code{toc0}
	\end{tabular}
\end{center}

The entries of the table of contents might be changed by other settings independent of this package options.

The \code{hyperref}-option produces links inside of the document. This refers to the datatypes of parameters, classes, methodreturns, etc. It also produces many warnings during compilation process due to the missing targets. Using this option, the package \code{hyperref} is loaded. Options can be set with the \befehl{hypersetup} command.

The package provides the possibility to use different languages. It belongs to the headinds and words, no options or packages are loaded. Codespecific words are not translated. An implemented option is \code{deutsch}, default is english. Other languages can be easily integrated by translating the following commands. All language-commands start with \befehl{jd@lang@}, the endings are listed in table \ref{tab:jd:lang}.

\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{Language commands}
\end{table}

\section{Design-Commands}
2 additional commands are helpful. \befehl{jdinh} draws an arrow for inheritance from right to left. \befehl{jdcode} has one argument and changes the font to TrueType.

\section{Linking in the Output-PDF}
For linkings the arguments of \befehl{jdtype} and the first arguments of \befehl{JDpara} and \befehl{jdInhEntry} must contain the link-information. These information are set with \befehl{jdtypesimple\{type\}} or \befehl{jdtypearray\{name\}\{dimension\}} or \befehl{jdtypegeneric\{name\}\{generic\}}. For generic types the single classes must be signed with the named commands. The targets are set automatically. You can use all these commands without worrying about the use of the \code{hyperref} option. Without the option, the links are ignored and produces no errors or warnings.

\section{Known Issues}
\begin{itemize}
	\item Problems comes about the linkings to not described classes. There are warnings during compilation process and missing links in the output.
	\item Only class- and interfacenames are linked, not methods or else. 
	\item The label for linking contains the classname. Two equal named classes produces errors.
	\item Method- und Fieldnames often produces overfull boxes in the headings.
\end{itemize}

\section{Structure of a class}
The hierarchy levels are already mentioned, here comes the description. Describing a class starts with a classname. This name will be the highest hierarchy level. Then the headings for Fields, Methods, Constructors follow, the lowest level is for the elements of the class (methodnames, fieldnames...)

\section{Description of a class}
The outer environment for a class is \code{jdclass}. \code{jdclass} has an argument with the classname. An option can be given with the type \code{class} or \code{interface} or \code{enum}. Default is \code{class}. Inside of the class environment, the following structure has to be kept.

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

The environment \code{jdclassheader} can be written once per class, the environments \code{jdconstructor} and \code{jdinheritancetable} need no argument with the name.

\subsection{The environment \protect\code{jdinheritancetable}}
The table entries can be produced with the \befehl{jdInhEntry} command. It has two arguments, the first one is the element the second the class, that inherited the element.

\subsection{Commands for all environments except \protect\code{jdinheritancetable}}
For all environments the same elements are valid in general. But not all elements are used everywhere. The table \ref{tab:befehleInUmgebung} lists the usage of commands in environments. The usage of commands not belonging to an environment doesn't produces a failure, but it has no effect. The  \code{javadoc}-package has no java-syntax-check, you can call contradictory modifier if you feel to.

\subsubsection{Modifier}
The following modifier can be named. They have no arguments.
\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{Codebased Attributs}
The following attributes are not javadoc-based but contains important information

\begin{itemize}
	\item \befehl{jdpackage\{packagename\}} The package containing the class.
	\item \befehl{jdinherits\{classname\}} Inherited class. For a hierarchy, the arrow \befehl{jdinh} can be used.
	\item \befehl{jdimplements\{interface\}} A Interface, that is implemented. Can be named more than once.
	\item \befehl{jdouterclass\{classname\}} Defines an outer class for an inner one.
	\item \befehl{jdtype\{type\}} Data type, especially for return values, and fiels. A method without type gets automatically \code{void}.
\end{itemize}

\subsubsection{Javadocbased Attributs}
Most arguments have an argument containing their description.

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

There are three other attributs, that can be named more than once and/or contain more than one argument.
\begin{itemize}
	\item \befehl{JDsee\{description\}}
	\item \befehl{JDauthor\{authorname\}}
	\item \befehl{JDpara\{datatype\}\{name\}\{description\}}
	\item \befehl{JDthrows\{exceptionname\}\{description\}}
\end{itemize}

\subsection{Table with commands and environments}
The table \ref{tab:befehleInUmgebung} sums up, which commands can be named in which environment.

\begin{table}[!ht]
	\begin{center}
	\begin{tabular}{l|c|c|c|c }
		Command & \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\{description\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDcategory\{description\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDdeprecated\{description\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDsee\{description\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDserial\{description\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDserialData\{description\}}	&  &  & X & X
		\\ \hline
		 \befehl{JDserialField\{description\}}	&  & X &  & 
		\\ \hline
		 \befehl{JDsince\{description\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDtext\{description\}}	& X & X & X & X
		\\ \hline
		 \befehl{JDversion\{description\}}	& X & &  & 
		\\ \hline
		 \befehl{JDreturn\{description\}}	&  &  & X & X
		\\ \hline
		 \befehl{JDpara\{datatype\}\{name\}\{description\}} 	& & & X & X
		\\ \hline
		 \befehl{JDthrows\{exceptionname\}\{description\}} &  &  & X & X
	\end{tabular}
	\caption{Usage of commands in environments}
	\label{tab:befehleInUmgebung}
	\end{center}
\end{table}

\end{document}