From 92f1a949b7a0abcd3176e6f16a753176de3ec039 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 20 Apr 2004 13:25:06 +0000 Subject: [PATCH] Update document. git-svn-id: https://svn.dealii.org/trunk@9073 0785d39b-7218-0410-832d-ea1e28bc413d --- .../development/writing-documentation.html | 108 ++++++------------ 1 file changed, 35 insertions(+), 73 deletions(-) diff --git a/deal.II/doc/development/writing-documentation.html b/deal.II/doc/development/writing-documentation.html index 284cd7a407..4c399c3826 100644 --- a/deal.II/doc/development/writing-documentation.html +++ b/deal.II/doc/development/writing-documentation.html @@ -16,7 +16,7 @@ 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 + 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. @@ -55,27 +55,12 @@

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 + project, we use + doxygen. + 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/contrib/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 2000+ - pages, with tendencies to further growth), you will not want to do - that regularly, though. + JavaDoc standard.

@@ -83,8 +68,8 @@

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

       /**
@@ -112,42 +97,29 @@
       };
     
- kdoc will then generate a page for the class + doxygen 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.

-

- There is one exception to the rule that every member can be - documented separately: due to internal restrictions of the - kdoc2 tool by which the documentation is generated, - elements of en enumeration type (i.e. an enum object - in technical terminus) may not be documented right above their - declaration, but must be documented atop of the enum - declaration. (This is due to the fact that inside enums, - kdoc2 does not parse the elements separately at - present, but rather the whole enum as one.) -

-

Extended Layout

- In order to allow better structured output for long comments, we - have extended kdoc to understand the following - tags inside comments, which are partly borrowed from LaTeX like - languages: -