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.