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

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/