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.
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.
p.
Ing. Pierangelo Masarati OpenLDAP Core Team
SysNet s.n.c. Via Dossi, 8 - 27100 Pavia - ITALIA http://www.sys-net.it ------------------------------------------ Office: +39.02.23998309 Mobile: +39.333.4963172 Email: pierangelo.masarati@sys-net.it ------------------------------------------
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.
<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...
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/
Gavin Henry wrote:
<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...
But obviously I didn't know much about the typedef stuff. Good work!
OK, I think I overlooked your message. Usually, doxygen is not something I use too much with code I'm used to. But I had precise requirements for browsable description of the sources, and just running plain doxygen on OpenLDAP produces nothing really usable (for example, it pretends ldap.h and slap.h are empty files...) minly because it gets confused by the LDAP_P() macro.
I'm still checking if the results are complete, but now I've got something working acceptably.
p.
Ing. Pierangelo Masarati OpenLDAP Core Team
SysNet s.n.c. Via Dossi, 8 - 27100 Pavia - ITALIA http://www.sys-net.it ------------------------------------------ Office: +39.02.23998309 Mobile: +39.333.4963172 Email: pierangelo.masarati@sys-net.it ------------------------------------------
<quote who="Pierangelo Masarati">
Gavin Henry wrote:
<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...
But obviously I didn't know much about the typedef stuff. Good work!
OK, I think I overlooked your message. Usually, doxygen is not something I use too much with code I'm used to. But I had precise requirements for browsable description of the sources, and just running plain doxygen on OpenLDAP produces nothing really usable (for example, it pretends ldap.h and slap.h are empty files...) minly because it gets confused by the LDAP_P() macro.
I'm still checking if the results are complete, but now I've got something working acceptably.
Excellent! I'd love to see some API docs on the main site etc.
Would save folks in #ldap (howard) getting bombarded all the time ;-)
Thanks.
p.
Ing. Pierangelo Masarati OpenLDAP Core Team
SysNet s.n.c. Via Dossi, 8 - 27100 Pavia - ITALIA http://www.sys-net.it
Office: +39.02.23998309 Mobile: +39.333.4963172 Email: pierangelo.masarati@sys-net.it
-
Gavin Henry -
Howard Chu -
Pierangelo Masarati