Re: Code documentation trends

> On Wed, 2007-08-15 at 02:32 +0000, Amos Jeffries wrote:
<snip>
>> *** MemPool.h 23 Jun 2007 01:43:43 -0000 1.10.10.1
>> --- MemPool.h 15 Aug 2007 02:32:57 -0000 1.10.10.2
>> ***************
>> *** 120,124 ****
>> };
>>
>> ! /* Support late binding of pool type for allocator agnostic classes */
>> class MemAllocatorProxy
>> {
>> --- 120,126 ----
>> };
>>
>> ! /**
>> ! * Support late binding of pool type for allocator agnostic classes
>> ! */
>
> Did you add the two extra lines to make doxygen happy? Is there a less
> invasive way to accomplish the same? (Please do not interpret these
> questions as criticism, I am just trying to understand the motivation
> and doxygen limitations).

No, a block doc-comment only requires the /** at the beginning ,
everything else is arrangement and visual effect.
The extra lines like that are usually because I expect a full description
to go in there. Will be happening to all API stuff in .h, much less so on
Internals.

That one is also going to need a few doxygen tags like \ingroup and a
less-cryptic description. I didn't quite get time last night to go through
the Mem* component pieces and link them into a module.

Time for part 2 of the auto-docs lessons:

What I have settled on a week ago is a 'looks nice and can be read easily'
style, which requires people only to know that doc comments start with /**
and have " * " at the start of each line inside the comment.
Lines that start with " \foo" are special to the auto-docs and only to be
altered if understood (doxygen help is online for reference).
Do make any special formatting such as lists, paragraphing, large titles,
example code snippets require the doxygen commands. Formatting by
whitespace indentation (ie " - ") will no longer work.

What I'm hoping for is to have a paragraph for each class about where its
intended to be used etc.

Objects where I only have enough details to say this is part of X module,
are going in as "/// ..." for now (which I would like NOT to have in the
final code pushed to HEAD, its quite ugly to see "/// \FooBarInternals",
but it works).

Part 3 (module/component names and organisation, will have to come later
when I have a more certain list).

>
>> class MemAllocatorProxy
>> {
>> ***************
>> *** 138,143 ****
>> mutable MemAllocator *theAllocator;
>> };
>> /* help for classes */
>> ! /* Put this in the class */
>> #define MEMPROXY_CLASS(CLASS) \
>> /* TODO change syntax to allow moving into .cci files */ \
>> --- 140,154 ----
>> mutable MemAllocator *theAllocator;
>> };
>> +
>> /* help for classes */
>> ! /**
>> ! * Put this in the class
>> ! \code
>> ! class foo
>> ! {
>> ! MEMPROXY_CLASS(foo);
>> ! }
>> ! \endcode
>> ! */
>> #define MEMPROXY_CLASS(CLASS) \
>> /* TODO change syntax to allow moving into .cci files */ \
>
> Does this change work around some other doxygen limitation? Or are you
> trying to provide a better illustration of what "Put this in the class"
> means?

I was just copying the 'how to use' example as-is from the old SGML file.

\code and \endcode just tell doxygen its a piece of example code to be
displayed. Theres lots of little bits still need doing for the Mem
component.
You can see what it looks like at:
http://squid.treenet.co.nz/Doc/Code/MemPool_8h.dyn#2eab9a6fa490ed842eeee6a1800e0ec4

I think maybe it's the text-description not making it clear its a
code-example. That description needs fixing.

>
> None of these changes are a big deal, of course. I am just worried about
> the general trend of hiding code behind overly verbose documentation...
>
> Does doxygen support some kind of \include mechanism where verbose
> documentation can be moved away from the code while still being linked
> to specific code pieces? Detailed documentation is great, but if it
> makes the actual code difficult to see, it is doing more harm than good,
> IMO.

Yes, but that defeats the entire purpose of this project. Having the
documentation at the point of code where it will get noticed for change by
any average-joe editors altering that code. I don't expect it to be huge.

I've had a hard time converting the SGML because it references only 2.5
examples and function names, describing how they behave in 2.5, and had to
check each function operation and change some of it in migration.

>
>> ***************
>> *** 146,150 ****
>> static inline MemAllocatorProxy &Pool()
>>
>> ! /* put this in the class .h, or .cci as appropriate */
>> #define MEMPROXY_CLASS_INLINE(CLASS) \
>> MemAllocatorProxy& CLASS::Pool() \
>> --- 157,171 ----
>> static inline MemAllocatorProxy &Pool()
>>
>> ! /**
>> ! * Put this in the class .h, or .cci as appropriate
>> ! \code
>> ! class foo
>> ! {
>> ! MEMPROXY_CLASS(foo);
>> ! }
>> !
>> ! MEMPROXY_CLASS_INLINE(foo);
>> ! \endcode
>> ! */
>> #define MEMPROXY_CLASS_INLINE(CLASS) \
>> MemAllocatorProxy& CLASS::Pool() \
>
> Like this new documentation bug, for example. :-)

You see the examples aren't always right.

>
> Thank you,
>
> Alex.
>

Welcome.

Amos
Received on Wed Aug 15 2007 - 16:21:21 MDT