[Date Prev][Date Next] [Chronological] [Thread] [Top]

Re: Automatic code documentation: doxygen?



<quote who="Howard Chu">
> Pierangelo Masarati wrote:
>> I'm trying to automatically document OpenLDAP code.  Since I ha previous
>> experience with doxygen and C++, which looks pretty reliable and
>> versatile, I made some experiments, with less than encouraging results.
>>

Hey, I already asked this in Dec ;-)

http://www.openldap.org/cgi-bin/wilma_hiliter/openldap-devel/200612/msg00005.html

But obviously I didn't know much about the typedef stuff. Good work!

>> One of the key issues I'm facing is the need to handle the somewhat
>> quite involved use we often make of #defines.  Doxygen allows
>> sophisticated pre-processing, with lots of flexibility, which required a
>> bit of carving before, for instance, getting anything out of slap.h.
>>
>> Another issue is that we made some inconsistent use of typedefs for
>> structures.  For example, many key structures are typedef'd as
>>
>> typedef struct foo bar;
>>
>> This is very misleading, because doxygen documents that structure as
>> "foo", while most of the times it's used as "bar".  Maybe renaming
>> typedefs like
>>
>> typedef struct bar bar;
>>
>> would simplify things, so that the original and the typedef'd names
>> match.
>
> Agreed. That's always been the style I used in previous projects; I
> don't see any benefit to having struct names differ from their typedef.
>>
>> I'd rename things only in those cases the original name is never used in
>> practice.  For example, I wouldn't touch "struct berval", since it's
>> used almost everywhere, while "BerValue" is seldom used.  On the
>> contrary, I don't think "struct slap_attr_name" is ever used in the
>> code, while its typedef "AttributeDescription" is consistently used
>> everywhere.  The same is true for "Connection", "Operation", "SlapReply"
>> and so.
>>
>> If anyone is interested in doxygen docs, I'll be happy to share my
>> Doxyfile as soon as it's consolidated.
>
> Sounds like a good resource.
>
> --
>    -- Howard Chu
>    Chief Architect, Symas Corp.  http://www.symas.com
>    Director, Highland Sun        http://highlandsun.com/hyc
>    Chief Architect, OpenLDAP     http://www.openldap.org/project/
>