From: Andre Noll Date: Tue, 1 Sep 2015 17:28:19 +0000 (+0200) Subject: manual: Improve section on Doxygen. X-Git-Tag: v0.5.6~86 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=37a1f8ae30afb83f6d2187dcdbb30feec57f104b manual: Improve section on Doxygen. It was longer than necessary and a bit clumsy to read. The new formulation is shorter and more to the point. --- diff --git a/web/manual.m4 b/web/manual.m4 index 0963306e..d63b07e8 100644 --- a/web/manual.m4 +++ b/web/manual.m4 @@ -2010,21 +2010,19 @@ Doxygen ~~~~~~~ Doxygen is a documentation system for various programming -languages. The paraslash project uses Doxygen for generating the API -reference on the web pages, but good source code documentation is -also beneficial to people trying to understand the code structure -and the interactions between the various source files. +languages. The API reference on the paraslash web page is generated +by doxygen. It is more illustrative to look at the source code for examples than -to describe the conventions for documenting the source in this manual, -so we only describe which parts of the code need doxygen comments, -but leave out details on documentation conventions. +to describe the conventions in this manual, so we only describe which +parts of the code need doxygen comments, but leave out details on +documentation conventions. As a rule, only the public part of the C source is documented with Doxygen. This includes structures, defines and enumerations in header files as well as public (non-static) C functions. These should be -documented completely. For example each parameter and the return -value of a public function should get a descriptive comment. +documented completely. For example, each parameter and the return +value of a public function should get a descriptive doxygen comment. No doxygen comments are necessary for static functions and for structures and enumerations in C files (which are used only within