The deal.II Homepage

From 1e5ed06e5aa9c5e62544f57340c763447e931fa1 Mon Sep 17 00:00:00 2001 From: wolf Date: Wed, 9 Feb 2000 14:52:47 +0000 Subject: [PATCH] Add file about writing documentation. git-svn-id: https://svn.dealii.org/trunk@2349 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/development/navbar.html | 7 + deal.II/doc/development/toc.html | 11 + .../development/writing-documentation.html | 244 ++++++++++++++++++ 3 files changed, 262 insertions(+) create mode 100644 deal.II/doc/development/writing-documentation.html diff --git a/deal.II/doc/development/navbar.html b/deal.II/doc/development/navbar.html index 9d26aebca2..21cabea191 100644 --- a/deal.II/doc/development/navbar.html +++ b/deal.II/doc/development/navbar.html @@ -27,6 +27,13 @@

+ Writing + documentation +

diff --git a/deal.II/doc/development/toc.html b/deal.II/doc/development/toc.html index 19c8d086ce..bd5e8c38bd 100644 --- a/deal.II/doc/development/toc.html +++ b/deal.II/doc/development/toc.html @@ -33,6 +33,17 @@ generic Makefiles, one for small and one for larger projects.

Writing + documentation: To document the library and our + application programs, we use a slightly patches version of + kdoc + which is one of the documentation tools of the + KDE + project. This page documents the basics of the format in + which the documentation needs to be written in order to + enable automatic documentation generation. +

Recent changes to the library: If you want to stay informed about what is going on with the library itself, your may want to take a diff --git a/deal.II/doc/development/writing-documentation.html b/deal.II/doc/development/writing-documentation.html new file mode 100644 index 0000000000..fe69e21aee --- /dev/null +++ b/deal.II/doc/development/writing-documentation.html @@ -0,0 +1,244 @@ + + + + + + + The deal.II Homepage - Makefiles + + + + + +

Writing Documentation

+ +

+ It is our firm belief that software can only be successful if it + is properly documented. Too many academic software projects die + prematurely once their creators leave the university or the + workgroup in which the software was developed since with their + creators also knowledge of internal structures, interfaces, and + the valuable bag of tricks leaves, a gap that can not be closed by + reading sources, trial-and-error, and guessing. +

+ +

+ The deal.II project has therefore from its + infancy adopted a policy that every aspect of the interface + needs to be well-documented before its inclusion into the + source tree. Since we have found that it is impossible to keep + documentation up-to-date if it is not written directly into the + program code, we write the documentation directly at the place of + declaration of a function or class and use automatic tools to + extract this information from the files and process it into HTML + for our web-pages, or LaTeX for printing. +

+ +

+ In addition to the API documentation, we maintain a series of + + well-documented example programs, which also follow a certain + ``literate programming'' style in that the explanations of what + is happening are integrated into the program source by means of + comments, and are extracted by small scripts. +

+ +

+ This document first explains the basics of + documenting the API and then of + writing example programs. +

+ + + +

Writing API documentation

+ +

+ In order to extract documentation from the header files of the + project, we use a modified version of + kdoc, + written by Sirtaj Singh Kang, + which is one of the documentation tools of the + KDE + project. It requires that documentation is written in a form which + closely follows the + + JavaDoc standard, with some small additions which we will + explain below. The patched version of kdoc is included into the + library and can be found in the + deal.II/doc/auto/script/kdoc directory. +

+ +

+ Alternatively, one can use + Doc++ to + create a LaTeX document from the sources which can then be + printed. Due to the size of the resulting file (at present 1500+ + pages, with tendencies to further growth), you will not want to do + that regularly, though. +

+ + +

Basic layout of documentation

+ +

+ Basically, every declaration, whether class or member + function/variable declaration, may be preceded by a comment of the + following form: + +

+      /**
+       * This is an example documentation.
+       *
+       * @author Wolfgang Bangerth, 2000
+       */
+      class TestClass 
+      {
+        public:
+                 /**
+		  * Constructor
+		  */
+          TestClass (); 
+
+                 /**
+		  * Example function
+		  */
+          virtual void test () const = 0;
+
+                 /**
+		  * Member variable
+		  */
+          const unsigned int abc;
+      };
+

+ kdoc will then generate a page for the class + TestClass and document each of the member functions + and variables. The content of the @author tag will be + included into the online documentation of the class. +

+ + +

Extended Layout

+ +

+ In order to allow better structured output for long comments, we + have extended kdoc to understand the following + tags inside comments (since they are LaTeX, they are understood by + the LaTeX output of Doc++ automatically): +

Itemized lists: +
+ By writing comments like the following, +
```
+	   /**
+	    * \begin{itemize}
+	    *   \item foo
+	    *   \item bar
+	    * \end{itemize}
+	    */
+	 
```
+ you can get itemized lists both in the online and printed + documentation: +
- foo +
- bar +
+
+ +
Verbatim output: +
+ If you write comments like this, +
```
+	   /**
+	    * \begin{verbatim}
+	    *   void foobar ()
+	    *   {
+	    *     i = 0;
+	    *   };
+	    * \end{verbatim}
+	    */
+	 
```
+ you will get the lines between the verbatim environment with + the same formatting and in typewriter font: + + void foobar () + { + i = 0; + }; + + This is useful if you want to include small sample code snippets + into your documentation. In particular, it is important that + the formatting is preserved, which is not the case for all + other text. +
+ +
Typewriter font: +
+ One would often like to use a typewriter font for variable, + function, or class names. For this, Doc++ has the special + sequence #...#, which generates output in which + the content inside the # characters is set in + typewriter font. We have extended kdoc for this feature as well. +
+ +
+ As a convention, we always enclose variable and function + names into #...# in order to give them a visible + distinction. +
+ +
Sections: +
+ Sections can be generated using + \section{...}, \subsection{...}, + \subsubsection{...} tags. +
+

+ + + +

Future directions

+ +

+ In the not-so-far future, we hope to be able to switch to + kdoc2, + which offers a much nicer output and a greatly improved parser. At + present, this program is still in alpha stage, but once stable we + will use for the generation of documentation. In particular, we + will then start thinking about using kdoc also for the generation + of printable documentation, through its SGML backend. +

+ +

+ Speaking of SGML, we are considering switching to SGML + altogether. At present, printing of some documentation, most + notably the example programs is not really supported, and we + consider ways to convert them to SGML along with most other + documentation, since SGML is readily convertible into many other + formats, for example HTML and Postscript. +

+ +

+ Switching to SGML would also include replacing the LaTeX-like + layout extensions described above by their SGML alikes. However, + since this is not imminent, you need not care about this at + present. +

+ + + +

Writing example programs

+ + + +

+ +

+ The deal.II group

+ + + + -- 2.39.5