RE: [Doxygen-users] Documenting an 3rd party SDK

[Glenn M. <gle...@vo...>]

Hi Yves,

If I were you, I would get that 3rd party developer to comment their
code, e.g. put Doxygen comments into the header files. You could do it
yourself and send them the updated file and ask them to start using
it/distributing it. Hopefully they are open-minded enough to realize
that commented code is an asset; if they want people to use their SDK,
then put comments in it.

If this preferred method fails due to politics or whatnot, you can fake
out Doxygen. You can put all of your Doxygen comment blocks into a
separate file (e.g., txt). In order to get them to map to the correct
code element, you have to put in a command like @fn or @cl (etc.)
followed by the **exact** prototype on one line at the beginning of each
comment block.

The problem with this technique is that the prototype has to match. If
that 3rd party developer changes their header file, the results will be
code items without comments and nicely worded comments falling through
the cracks if the prototype doesn't match anything in the header files.
It can be a maintenance chore.

Back to my original idea, if you did the first pass at documenting the
header file using Doxygen, you could use (1) reason, (2) business case
justification, (3) clout, (4) executive pressure, etc. to get the 3rd
party developer not only to accept your work but also to maintain it
from then on [or give you a crack at maintaining it.] Either way, it
would actually be a pretty good deal for them and make their SDK even
more marketable.

Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
gle...@vo...


> -----Original Message-----
> From: Yves Poissant [mailto:ypo...@mi...]
> Sent: Monday, November 26, 2001 8:55 PM
> To: dox...@li...
> Subject: [Doxygen-users] Documenting an 3rd party SDK
>=20
>=20
> Hi everybody.
>=20
> I would like to use Doxygen to document a 3rd party SDK. The=20
> SDK is being
> updated about every 2 weeks by the company. All I have are=20
> the *.lib, the *.h in
> the include directory and some plugin examples (the SDK is=20
> for developing
> plugins for a 3D animation package) as complete Visual C++=20
> projects with source
> and all. The include files contains about no documentation meaning no
> documentations for classes or members or whatever. Obviously,=20
> I don't want to
> add the documentation inside the header files since they will=20
> change regularly.
> I would like to have Doxigen combine documentation for the=20
> classes and members
> and all that from some external independent documentation=20
> files. Anyone have any
> suggestion as to how to accomplish that?
>=20
> I was thinking of writing some fake implementation files that=20
> would parallel
> each header files in which I would add the documentation. I=20
> can see how to
> document member functions using this trick but how could I=20
> document member
> variables?
>=20
> Is there any other easier way to do that?
>=20
> What about using tag files for this?
>=20
> Do I misunderstand the use of tag files?
>=20
> Yves Poissant
>=20
>=20
>=20
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>=20