Code documentation trends

On Wed, 2007-08-15 at 02:32 +0000, Amos Jeffries wrote:
> Update of cvs.devel.squid-cache.org:/cvsroot/squid/squid3/include
>
> Modified Files:
> Tag: docs
> MemPool.h
> Log Message:
> Commenting style change.
>
>
> Index: MemPool.h
> ===================================================================
> RCS file: /cvsroot/squid/squid3/include/MemPool.h,v
> retrieving revision 1.10.10.1
> retrieving revision 1.10.10.2
> diff -C2 -d -r1.10.10.1 -r1.10.10.2
> *** 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).

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

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.

> ***************
> *** 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. :-)

Thank you,

Alex.
Received on Wed Aug 15 2007 - 09:52:06 MDT