[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/
>