[thesis] Fixed mistakes, added examples for latex/doxygen. fixed style related issues
[hsd_doku_tool.git] / doc / thesis / chapters / softwaredokumentationen.tex
1 \chapter{Softwaredokumentationen}
2 \label{cha:Softwaredokumentationen}
3
4
5 Im folgenden Kapitel wird allgemein das Thema Dokumentationen im Softwarebereich beleuchtet. Es wird auf die verschiedenen Dokumentationstypen
6 eingegangen, allgemeine Probleme vorgestellt und Konzepte, die diese Probleme lösen können werden präsentiert. Außerdem werden Programme aufgezeigt, die
7 diese Konzepte zum Teil umsetzten, und somit bei der Erstellung von Dokumentationen helfen können.
8
9 \section{Allgemeine Eigenschaften}
10
11 Der Begriff Softwaredokumentation ist in der Literatur nicht einheitlich definiert, generell kann man aber Dokumentationstypen daran unterscheiden, für
12 welche Zielgruppe sie gedacht sind. Zwei wichtige Typen sind die Benutzerdokumentation und die Systemdokumentation.
13
14 \subsection{Benutzerdokumentation}
15
16 Die Benutzerdokumentation ist für die Anwender eines Programmes gedacht und besitzt einen anleitenden Charakter. Hier wird beschrieben, wie das Programm zu handhaben ist und welche Funktionen es
17 bietet. Es wird weniger auf technische Details eingegangen, sondern die Handhabung von für Benutzer bestimmte grafische Programmoberflächen erläutert \cite{Sommerville}.
18
19 \subsection{Systemdokumentation}
20 Als Systemdokumentation versteht man Quellcode und Schnittstellendokumentationen. Diese sind für Entwickler gedacht und helfen bei der Verwendung
21 von Programmbibliotheken und Entwicklungswerkzeugen. Entwickler können deren Arbeit selbst dokumentieren, damit sie ihre Gedankengänge zu einem
22 späteren Zeitpunk besser nachvollziehen können und um anderen einen leichteren Einstieg mit der Handhabung von entworfenen Schnittstellen zu ermöglichen \cite{Sommerville}.
23
24
25 \section{Dokumentationskonzepte}
26
27 Aufgrund der Schnelllebigkeit von Programmen und Zeitdruck in der Entwicklung wird oft schlecht bis gar nicht dokumentiert.
28 Dies ist vor allem im Bereich der Systemdokumentation ein sehr ausgeprägtes Problem. Als Beispiel kann man
29 hier, die von vielen Entwicklern vertretene Meinung, dass der Programmcode selbst Dokumentation genug sei anführen.
30 Um diesem Problem entgegenzuwirken, gibt es verschiedene Ansätze und Konzepte. Zwei bekannte Konzepte nennen sich
31 \textit{Literate Programming} und \textit{Elucidative Programming}.
32
33
34 \subsection{Literate Programming}
35 \label{ssec:LiterateProgramming}
36 Unter \textit{Literate Programming} versteht man den Versuch, nicht mehr einen Computer anzuweisen was er zu tun hat, sondern Menschen zu erklären was
37 von einem Computer gefordert wird. Dies geschieht unter anderem durch Wahl passender Variablennamen und der Erklärung von Codesegmenten
38 direkt im Quellcode mithilfe von speziellen Quellcodekommentaren. Später kann dann aus dem Programmcode mithilfe dieser Kommentare
39 ein Dokument in verschiedenen Ausgabeformaten erzeugt werden. Somit erhält man eine Dokumentation und einen nachvollziehbar lesbaren
40 Programmcode \cite{LiterateProgramming}.
41
42 \subsection{Elucidative Programming}
43 \label{ssec:ElucidativeProgramming}
44 \textit{Elucidative Programming} kann als Variante des \textit{Literate Programming} verstanden werden und verfolgt die Strategie bestehenden Programmcode in ein
45 Dokument einzubinden. Programmcode und Dokumentation sind hier getrennt. Änderungen im Code werden direkt in das Dokument übernommen.
46 Dies hat den Vorteil, dass man die Dokumentation nicht an zwei Stellen warten muss und dass das Quellprogramm ohne eingebetteter
47 Dokumentation intakt bleibt. Auch hier kann eine Dokumentation in verschiedenen Ausgabeformaten generiert werden \cite{ElucidativeProgramming}.
48
49 \section{Unterstützende Programme}
50
51 Um mit diesen Konzepten arbeiten zu können, gibt es verschiedene freie Programme. Als die Bekanntesten kann man \emph{Doxygen} \ref{ssec:Doxygen} und \emph{\latex} \ref{ssec:Latex} anführen. Diese
52 werden im folgenden Abschnitt genauer erläutert.
53
54
55 \subsection{\latex}
56 \label{ssec:Latex}
57 \textit{\latex} ist ein Formatierungsprogramm, das über eine Auszeichnungssprache die Formatierung von in einem gewöhnlichen Editor geschriebenem Text
58 ermöglicht. Diese Textformatierung erfolgt über Steuerbefehle. Somit zwingt es den Anwender sich rein auf den Inhalt zu
59 konzentrieren und nicht auf die Formatierung selbst \cite[Kapitel 1]{LatexEinfuehrung} \cite[Seite 8]{LatexFriends}.
60 \textit{\latex} eignet sich sehr gut für \emph{Elucidative Programming} \ref{ssec:ElucidativeProgramming}, da Programmcodes einfach mithilfe von bestehenden Makros eingebunden und beschrieben
61 werden kann.
62
63 \subsubsection{Beispiel}
64
65 In diesem Beispiel wird gezeigt, wie man Teile einer Quellcodedatei mithilfe von \textit{\latex} in ein Dokument einbindet und eine Dokumentation
66 generiert. Zur Veranschaulichung wurde folgender Programmcode herangezogen:
67 \lstinputlisting[language=C++,caption={einfaches C++ Beispielprogramm}]{examples/latex/exmpl_add_latex.cpp}
68
69 Um die Funktion \textit{add} beschreiben zu können, soll diese in ein Dokument eingefügt werden. Wie dies zu bewerkstelligen ist, kann
70 aus folgendem \latex-Dokument entnommen werden:
71
72 \lstinputlisting[caption={Einbinden von Quellcode in \textit{\latex}}]{examples/latex/docu.tex}
73 Die Funktionalität zum Einbinden von Quellcodedateien wird von dem \latex-Paket \textit{listings} bereitgestellt. Dieses Paket stellt
74 den Befehl \textit{lstinputlisting} zur Verfügung, der in diesem Beispiel mit folgenden Konfigurationsparametern verwendet wurde:
75 \begin{itemize}
76 \item \textbf{numbers:} Gibt an, wo sich die Zeilennummerierung für das eingebundene Dokument befindet.
77 \item \textbf{language:} Mithilfe dieses Parameters lässt sich eine Syntaxhervorhebung für verschiedene Programmiersprachen einstellen.
78 \item \textbf{firstnumber:} \textit{Firstnumber} konfiguriert, mit welcher Zahl die Zeilennummerierung im generierten Dokument startet.
79 \item \textbf{firstline:} Dieser Parameter bestimmt, ab welcher Zeile das Einbinden der Quellcodedatei gestartet wird.
80 \item \textbf{lastline:} Gibt an, bis zu welcher Zeile die Quellcodedatei einzubinden ist.
81 \end{itemize}
82 Eine umfangreiche Dokumentation des \textit{listings} \latex-Paketes findet sich in \cite{listingsDoc}.
83 \newline
84 \par
85 Um aus dem \latex-Quellcode ein PDF-Dokument zu generieren, muss das Kommandozeilenprogramm \textit{pdflatex} mit dem \latex-Dokument
86 als Parameter ausgeführt werden. Folgender Befehl führt diese Operation aus:
87
88 \begin{lstlisting}
89 $ pdflatex docu.tex
90 \end{lstlisting}
91
92 Das generierte PDF-Dokument mit der eingebundenen \textit{add}-Funktion wird in Abb.~\ref{fig:latexExample} dargestellt.
93
94 \begin{tcolorbox}[enhanced,colback=white,colframe=black,coltitle=black,title={\refstepcounter{figure}
95        \textbf{Abbildung \thefigure:} Diese Abbildung zeigt die generierte PDF-Dokumentation.
96        \label{fig:latexExample}},
97        attach boxed title to bottom left,
98        boxed title style={
99        enhanced, colback=white, colframe=white
100       }]
101 \subsubsection{Addieren}
102 Diese C++ Funktion gibt die Summe zweier Zahlen retour.
103
104     % Befehl zum Einbinden
105     \lstinputlisting[numbers=left,
106                     language=C++,
107                     firstnumber=3,
108                     firstline=3,
109                     lastline=6]{examples/latex/exmpl_add_latex.cpp}
110 \end{tcolorbox}
111
112 \subsection{Doxygen}
113 \label{ssec:Doxygen}
114 \textit{Doxygen} ist ein Programm zum Generieren von Dokumentationen aus einem Programmquellcode.
115 Es ist möglich mithilfe von definierten Steuerbefehlen in den Kommentarblöcken Schnittstellen und Klassen zu beschreiben.
116 Mithilfe von diesen Kommentaren kann man Dokumentationen in verschiedenen Ausgabeformaten erzeugen \cite{DoxyGen}. Dies bedeutet, dass das
117 Konzept von \emph{Literate Programming} \ref{ssec:LiterateProgramming} für Schnittstellen und Klassen umgesetzt wird.
118
119 \subsubsection{Beispiel}
120
121 Dieses Beispiel zeigt, wie die Doxygen-Steuerbefehle funktionieren und wie man mithilfe von \textit{Doxygen} eine Schnittstellendokumentation
122 erstellen kann. Zur veranschaulichung der Funktionsweise wurde folgender Quellcode mit einem Doxygen-Kommentarblock für die Funktion
123 \textit{add} erstellt:
124
125 \lstinputlisting[language=C++,caption={Beispielprogramm mit Doxygen-Kommentarblock}]{examples/doxygen/exmpl_add_doxy.cpp}
126
127 Im Beispielprogramm wurden folgende Steuerbefehle verwendet:
128 \begin{itemize}
129 \item \textbf{brief:} Mit diesem Befehl ist es möglich, eine allgemeine Funktionsbeschreibung anzugeben.
130 \item \textbf{param:} Mithilfe von param kann man die einzelnen Übergabeparameter einer Funktion beschreiben.
131 \item \textbf{return:} Der Steuerbefehl return erlaubt das Beschreiben des Rückgabewertes.
132 \end{itemize}
133 Weitere Steuerbefehle finden sich in \cite{DoxyGen}.
134 \newline
135 \par
136 Damit \textit{Doxygen} die Quellcodedatei verarbeiten kann, wird eine Konfigurationsdatei benötigt. Eine solche Datei wird in der Regel mit
137 dem Namen \textit{doxyfile} abgespeichert. Wie eine solche Konfigurationsdatei auszusehen hat, kann aus folgendem Beispiel entnommen
138 werden:
139
140 \lstinputlisting[caption={Minimale Doxygen Konfigurationsdatei}]{examples/doxygen/doxyfile}
141 Diese Datei zeigt nur die grobe Funktionsweise der Konfiguration. Eine umfangreiche Beschreibung aller möglichen Konfigurationsparameter
142 findet sich in \cite{DoxyGen}.
143 \newline
144 \par
145 Um eine Dokumentation zu generieren, muss man \textit{Doxygen} mit der entsprechenden Konfigurationsdatei als Parameter von der
146 Kommandozeile aus ausführen. Dies geschieht mit folgendem Befehl:
147
148 \begin{lstlisting}
149 $ doxygen doxyfile
150 \end{lstlisting}
151
152 Mit \textit{Doxygen} kann man Dokumentationen in verschiedenen Ausgabeformaten erzeugen. Wird in der Konfigurationsdatei kein Ausgabeformat
153 angegeben, wird die Dokumentation standardmäßig im \textit{html} und im \latex-Format erstellt.
154 Die generierte Schnittstellendokumentation der Funktion \textit{add} wird in Abb.~\ref{fig:doxyExample} dargestellt.
155
156 \begin{figure}[H]%
157     \centering
158     \subfloat[Ausgabe in \textit{html}]{{\includegraphics[width=0.4\textwidth]{doxy_html} }}%
159     \qquad
160     \subfloat[Ausgabe in \textit{\latex}]{{\includegraphics[width=0.4\textwidth]{doxy_latex} }}%
161     \caption{Diese Abbildung zeigt die generierten Dokumentationen im \textit{html} und \textit{\latex} Format.}%
162     \label{fig:doxyExample}%
163 \end{figure}
164