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.
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
> 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
> typedefs like
> typedef struct bar bar;
> would simplify things, so that the original and the typedef'd names
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
> 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",
> 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/