|
|
Ublas : |
From: Gunter Winkler (guwi17_at_[hidden])
Date: 2005-05-19 05:47:35
On Thursday 19 May 2005 10:48, Andreas Klöckner wrote:
> This looks easy enough to understand that writing a script to do some
> sort of transformation sounds really doable. However, I'm still not sure
> what you're getting at: Would the old documentation and the new
> Doxygen-generated stuff just coexist side-by-side?
There are parts of the documentation, that are independent of the
implementation. So it can be maintained independently.
> Would the HTML
> documentation be merged into the code, and spit back out by Doxygen? If
> so, what's the point of not just using Doxygen's output?
I started to write inline documentation but I didn't have the time to include
all the HTML docs into some source files. Personally, I would prefer to have
doxygen generate almost all of the docs about classes and concepts, but there
is still nobody who does the work (and I want to use most of my time for my
PhD).
On the the other hand I do not know how well doxygen integrates with boostbook
(which IMO is the ultimate goal). And finally, there was no clear decision
how to document classes in the future, because fixing bugs and improving
performance is still a more important task than creating new features. ("Ugly
doc is better than no doc at all.")
What do the others think about documentation style?
In order to have a simple documentation of all (important) classes and class
members its enough to write one line like
/// \brief this function does something
before each class/member/function definition.
to be more verbose you can use
/** \brief brief desciption
* many lines of long description
*/
(the type of the comment does not matter, but each line should start with 3
slashes /// or the first line with 2 asterisks /** ... */)
mfg
Gunter