Hi Jose and others,
Jose Luis Zabalza wrote:
>
> I come back again about the idea of ** what ** do
> a function or ** how ** do the function his work.
> I believe is important the documentation show two
> things.
>
> Doxigen is wonderful but not scan inside the
> function and I believe that inside the function
> must be the comments that say ** how ** the
> function work.
> [...]
Just to add my opinion. I tend to put quite
descriptive blocks of comments into the function
bodies. I feel that it is the more important the
larger the project is. It's because after a
while you do not know what you wrote earlier, and
it is much easier to remind the functionality by
reading good, human-readable comments that by
reexamining the commands.
On the other hand, any function should be on a
bit higher level of abstraction than the things
inside the body. Because of this, the comment
for the whole function (member function) should
be more abstract. My experience is that you get
less when you dig-out too much details. While
you may want to extract some points about how the
function works, for me it is much easier to
sketch the idea more roughly in the comment
outside the body.
If you want even more details, you can use
INLINE_SOURCES = YES
SOURCE_BROWSER = YES
in your Doxyfile.
In my opinion, it is much better to have some
global, more abstract view of the problem, and to
be able to go to details (if needed) quickly --
via automatically generated HTML links, for
example. (Doxygen is fairly good in it.)
Once your project and documentation gets bigger,
you will appreciate other features than digging
out as much details as possible. The opposite
may be desired. If the printed documentation
would have 2000 pages, nobody would ever read and
study it. Then you will quickly start to switch
off some types of diagrams and some levels of
details. Then the debate about in-body comments
starts to be rather academic. (I once asked for
something similar just because it came to my mind
that it would be wonderful; I went through the
same stage as you are going through now -- so I
think that I can speak about having such
experience.)
Earlier, I worked as a university teacher (CS,
programming, OS, etc.). I have always taught
students to write good comments. It should be as
important and done so automatically as breathing.
One should learn typing by 10 fingers and write
down the ideas and human-readable explanantions
to comment blocks as soon as possible. (You will
hardly do it better later, if ever.) When writing
such a comment block, you should be as fluent in
thinking and writing as if you were thinking and
speaking to someone (well, the speed is not that
important). Adding some markup may break this
activity (you have to concentrate on syntax).
When writing Doxygen comments, it is another
matter. You write them systematically (like
\brief, \param, \return, \note, \bug, \todo,
\sa,...) because you know that they can be
usefully processed -- much more usefully than the
points extracted for the body of a function.
This is just my opinion. The decision to accept
it or not is yours.
With regards,
Petr
--
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...
|
