Recent changes to Automatic Documentation

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Fri, 22 Mar 2013 18:34:41 -0000

--- v28
+++ v29
@@ -38,13 +38,13 @@
 To parse the comments correctly, they should be put directly before the associated element. In the example below the member that is to be documented is the function "foo ()" and the comment is placed right in front. Members that can be documented are classes, functions, methods, structs etc. Comments often include the following:

 * A brief description, preceded by *@brief*, In the documentation you will find lists of all brief description of members of the same category grouped together.
-* A more detailed description. There is no *@detailed* expression. An empty line separates the brief from the detailed description.
-* A todo marker, preceded by *@todo*. In the documentation you will find it with *Related Pages* > *Todo List*.
+* A more detailed description. There is no *@detailed*-expression. An empty line separates the brief from the detailed description.
+* A todo marker, preceded by *@todo*. In the documentation you will find it at *Related Pages* > *Todo List*.

 For functions and methods:

 * A short description of every parameter, preceded by *@param* followed by the exact name of the parameter followed by the description.
-* A short description of the return value, preceded by *@return.
+* A short description of the return value, preceded by *@return*.

 This looks something like this:

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Fri, 22 Mar 2013 18:32:35 -0000

--- v27
+++ v28
@@ -66,7 +66,7 @@
 }
 ~~~~~~
 

-To document members of a class (like public variables), a struct, union or enum you can also put the comments right behind the members:
+To document members of a class (like public variables), a struct, a union or an enum you can also put the comments right behind the members:

 ~~~~~~
 struct foo {

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Fri, 22 Mar 2013 18:31:55 -0000

--- v26
+++ v27
@@ -35,18 +35,18 @@

 Edit the Documentation

-To parse the comments correctly, they should be put directly before the associated element. Elements that can be documented are classes, functions, methods, structs etc. Comments often include the following:
+To parse the comments correctly, they should be put directly before the associated element. In the example below the member that is to be documented is the function "foo ()" and the comment is placed right in front. Members that can be documented are classes, functions, methods, structs etc. Comments often include the following:

-* A brief description, which is displayed in lists of elements of the same category.
-* A more detailed description.
-* A todo marker, that will be linked in a todo-list.
+* A brief description, preceded by *@brief*, In the documentation you will find lists of all brief description of members of the same category grouped together.
+* A more detailed description. There is no *@detailed* expression. An empty line separates the brief from the detailed description.
+* A todo marker, preceded by *@todo*. In the documentation you will find it with *Related Pages* > *Todo List*.

 For functions and methods:

-* A short description of every parameter.
-* A short description of the return value.
+* A short description of every parameter, preceded by *@param* followed by the exact name of the parameter followed by the description.
+* A short description of the return value, preceded by *@return.

-They look something like this:
+This looks something like this:

 ~~~~~~
 /** @brief Brief description of foo().
@@ -56,13 +56,22 @@
     @param p1 Short description of p1.
     @param p2 Short description of p2.

-    @result Short description of the return value.
+    @return Short description of the return value.

     @todo Short todo-note.
 */

 int foo(int p1, double p2) {
     ...
+}
+~~~~~~
+

+To document members of a class (like public variables), a struct, union or enum you can also put the comments right behind the members:
+
+~~~~~~
+struct foo {
+    int p1; ///< Short description of p1.
+    double p2; ///< Short description of p2.
 }
 ~~~~~~

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Wed, 12 Dec 2012 19:18:19 -0000

--- v25
+++ v26
@@ -71,6 +71,7 @@
 Now, whenever you want to make your modifications in the comments visible, just save the file, type "doxygen" on the shell (while in the project directory) and open the index.html or update the file in the browser (hit F5).
 
 To change the settings for the Doxygen-parser, edit the Doxyfile with a text editor. Some things you can specify are...
+
 * ...the output destination
 * ...the output format
 * ...the presence/absence of a todo- and other lists

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Wed, 12 Dec 2012 19:17:47 -0000

--- v24
+++ v25
@@ -70,4 +70,9 @@
 
 Now, whenever you want to make your modifications in the comments visible, just save the file, type "doxygen" on the shell (while in the project directory) and open the index.html or update the file in the browser (hit F5).
 
-To change the settings for the Doxygen-parser, edit the Doxyfile with a text editor. You can specify, for example, the output destination, some design aspects, 
+To change the settings for the Doxygen-parser, edit the Doxyfile with a text editor. Some things you can specify are...
+* ...the output destination
+* ...the output format
+* ...the presence/absence of a todo- and other lists
+* ...the color scheme
+* ...many other design aspects

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Wed, 12 Dec 2012 19:12:01 -0000

--- v23
+++ v24
@@ -1,4 +1,4 @@
-We use a tool called **Doxygen** to create automatic documentation from javadoc-style commands in the code. This page is a short introduction on how to use Doxygen for this project. You can find more information in the [Doxygen manual](http://www.stack.nl/~dimitri/doxygen/manual.html).
+We use a tool called **Doxygen** to create automatic documentation from comments in the code. This page is a short introduction on how to use Doxygen for this project. You can find more information in the [Doxygen manual](http://www.stack.nl/~dimitri/doxygen/manual.html).
 
 [1 Installation](#1)
 [2 Create the Documentation](#2)
@@ -25,7 +25,7 @@
 ---
 
 Create the Documentation
-Doxygen automatically creates the documentation using comments in the source code conforming to a certain syntax. The output is a fully designed HTML, PDF or Latex (quite some other output formats are possible). So you don't need to give much thought to the formatting or structure of your documentation.
+Doxygen automatically creates the documentation parsing the source code for comments conforming to a certain syntax. The output is a fully designed HTML, PDF or Latex (quite some other output formats are possible). So you don't need to give much thought to the formatting or structure of your documentation.
 
 To create the documentation you need a settings file first. There is already one in the repository, named *Doxyfile*.\* Then type "doxygen" on the shell while in the project folder. As of now (2012-12-12) the output is html. To view it, just open the *index.html* in the newly created folder *html* in the project directory.
 
@@ -49,9 +49,9 @@
 They look something like this:
 
 ~~~~~~
-/** @brief Brief description.
+/** @brief Brief description of foo().
 
-    Detailed description.
+    Detailed description of foo().
 
     @param p1 Short description of p1.
     @param p2 Short description of p2.
@@ -66,6 +66,8 @@
 }
 ~~~~~~
 

-Doxygen provides many expressions. Sometimes there are several syntax expressions that all mean the same thing in order to accomodate for different popular commenting styles. But this is not important as long as you dont want to dig deeper. The information in this guide and a short look at some examples in the code and at the corresponding output should suffice to enable you to contribute to the documentation.
+Doxygen provides many expressions. Sometimes there are several syntax expressions that all mean the same thing in order to accomodate for different popular commenting styles (like in Javadoc- or Qt-style documentation). But this is not important as long as you dont want to dig deeper. The information in this guide and a short look at some examples in the code and at the corresponding output should suffice to enable you to contribute to the documentation.
 
 Now, whenever you want to make your modifications in the comments visible, just save the file, type "doxygen" on the shell (while in the project directory) and open the index.html or update the file in the browser (hit F5).
+
+To change the settings for the Doxygen-parser, edit the Doxyfile with a text editor. You can specify, for example, the output destination, some design aspects,

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Wed, 12 Dec 2012 19:04:59 -0000

--- v22
+++ v23
@@ -67,3 +67,5 @@
 ~~~~~~
 

 Doxygen provides many expressions. Sometimes there are several syntax expressions that all mean the same thing in order to accomodate for different popular commenting styles. But this is not important as long as you dont want to dig deeper. The information in this guide and a short look at some examples in the code and at the corresponding output should suffice to enable you to contribute to the documentation.
+
+Now, whenever you want to make your modifications in the comments visible, just save the file, type "doxygen" on the shell (while in the project directory) and open the index.html or update the file in the browser (hit F5).

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Wed, 12 Dec 2012 18:53:10 -0000

--- v21
+++ v22
@@ -1,4 +1,4 @@
-We use a tool called **Doxygen** to create automatic documentation from javadoc-style commands in the code. This page is a short guide on how to use Doxygen for this project. For 
+We use a tool called **Doxygen** to create automatic documentation from javadoc-style commands in the code. This page is a short introduction on how to use Doxygen for this project. You can find more information in the [Doxygen manual](http://www.stack.nl/~dimitri/doxygen/manual.html).
 
 [1 Installation](#1)
 [2 Create the Documentation](#2)
@@ -17,7 +17,7 @@
 If this doesn't work or you dont want to use Linux, refer to the [installation guide](http://www.stack.nl/~dimitri/doxygen/install.html) on the Doxygen homepage.
 
 Optional:
-If Doxygen is supposed to be able to draw graphs, you will need the graph-toolkit **graphviz**.In fact, this is used in the OSOLSim documentation and if you dont have graphviz Doxygen might throw an error, unless you disable graphs in the doxyfile.txt.
+If Doxygen is supposed to be able to draw graphs, you will need the graph-toolkit **graphviz**.In fact, this is used in the OSOLSim documentation and if you dont have graphviz Doxygen might throw an error, unless you disable graphs in the *Doxyfile*.
 Use the Ubuntu Software Center for the installation. If you dont have Ubuntu, view the [download page](http://www.graphviz.org/Download..php) on the graphviz website. The easiest way is probably to scroll down and download the Third-Party Executable Packages.
 
 If you want PDF, Latex or Postscript output, you need a Latex distribution.
@@ -27,7 +27,9 @@
 Create the Documentation
 Doxygen automatically creates the documentation using comments in the source code conforming to a certain syntax. The output is a fully designed HTML, PDF or Latex (quite some other output formats are possible). So you don't need to give much thought to the formatting or structure of your documentation.
 
-To create the documentation just type "doxygen" on the shell while in the project directory. As of now (2012-12-12) the output is html. To view it, just open the *index.html* in the newly created folder *html* in the project directory.
+To create the documentation you need a settings file first. There is already one in the repository, named *Doxyfile*.\* Then type "doxygen" on the shell while in the project folder. As of now (2012-12-12) the output is html. To view it, just open the *index.html* in the newly created folder *html* in the project directory.
+
+\*In the case that for some reason there is **no** settings file you can create one on your own typing "doxywizard" on the shell and following the wizard.
 
 ---
 
@@ -63,3 +65,5 @@
     ...
 }
 ~~~~~~
+

+Doxygen provides many expressions. Sometimes there are several syntax expressions that all mean the same thing in order to accomodate for different popular commenting styles. But this is not important as long as you dont want to dig deeper. The information in this guide and a short look at some examples in the code and at the corresponding output should suffice to enable you to contribute to the documentation.

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Wed, 12 Dec 2012 18:24:11 -0000

--- v20
+++ v21
@@ -1,5 +1,3 @@
-
-
 We use a tool called **Doxygen** to create automatic documentation from javadoc-style commands in the code. This page is a short guide on how to use Doxygen for this project. For 
 
 [1 Installation](#1)
@@ -47,7 +45,8 @@
 * A short description of the return value.
 
 They look something like this:
-
+
+~~~~~~
 /** @brief Brief description.
 
     Detailed description.
@@ -63,6 +62,4 @@
 int foo(int p1, double p2) {
     ...
 }
-
-
-
+~~~~~~

WikiPage Automatic Documentation modified by Henning Schindler

Henning Schindler — Wed, 12 Dec 2012 18:15:30 -0000

--- v19
+++ v20
@@ -1,3 +1,5 @@
+
+
 We use a tool called **Doxygen** to create automatic documentation from javadoc-style commands in the code. This page is a short guide on how to use Doxygen for this project. For 
 
 [1 Installation](#1)
@@ -62,4 +64,5 @@
     ...
 }
 
-
+
+