From: wolf Date: Wed, 9 Feb 2000 14:52:47 +0000 (+0000) Subject: Add file about writing documentation. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1e5ed06e5aa9c5e62544f57340c763447e931fa1;p=dealii-svn.git Add file about writing documentation. git-svn-id: https://svn.dealii.org/trunk@2349 0785d39b-7218-0410-832d-ea1e28bc413d --- 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): +

    +

    + + + +

    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
    + + + +