Re: Automatic code documentation: doxygen?

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

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