[Doxygen-users] Re: Documenting enums of an IDL file

[Don M. <dmc...@in...>]

Francois,

First, I for one would appreciate it if you (and others) would not post HTML
messages to the group. If you subscribe to the digest form of the list, as I
do, you can't get HTML messages (well, you can, but if you select that
option then they all end up as separate messages again, kind of defeating
the purpose). HTML messages are difficult to read if you aren't reading them
in html. Thanks.

Now, regarding enums in IDL. I have no problems getting Doxygen to generate
documentation for global enums in an IDL file. This is in an ATL project, as
well. However, I am still using Doxygen 1.2.6, because there's been no
reason for me to upgrade. So perhaps it is a problem in newer versions? Or
perhaps there is something slightly "wrong" (different) about your enum
declaration? Or perhaps it is actually there but you haven't seen it
(because it is with other global objects, not on an interface documentation
page)?

As an example, we use:

  /** Enum for visibility of a scalar in the UI and/or results database. */
  typedef [uuid(e1933138-11cb-11d5-93e6-00a024d4dc52)] enum enumVisibility
  {
    Enabled = 0,		///< Visible and enabled
    Disabled = 1,		///< Visible, but disabled (grayed)
    Hidden = 2		///< Not visible
  } enumVisibility;

This is before the first interface definition, not inside it, as you
describe. Works fine. Because it's a global, the enum documentation shows up
on the "Something.idl File Reference" page, but it's correctly hyper-linked
where it's used, so that doesn't bother me much.

For what it's worth, there are other problems with using Doxygen to process
Microsoft IDL files, that make it perhaps not the best tool (and that I
think are bigger issues than enums). Doxygen does not lump the propget and
propput signatures into one "property" in the documentation, which makes the
generated documentation confusing, and is annoying if you only want to write
the documentation once and have it apply to both get and put (no way to do
that). And the documentation shows C++ syntax, so it is not very useful to,
say, VB programmers.

Depending on your project, you might consider:
a. Using a preprocessing (or post-processing) script to make the
documentation better.
b. Making changes to Doxygen itself.
c. Looking at other tools. I have seen tools that produce documentation
based in the "helpstring" entry in the IDL file.

I haven't tried any of these myself.

The advantage of Doxygen for IDL files is the excellent hyper-linking. Our
IDL describes a large number of objects (interfaces), which make up a
complex object model for our system. Objects contain collections of other
objects, etc. It's nice to be able to click on the parameter to one method
in an interface, and immediately jump to the definition of that object's
interface.

Good luck.

Don McClimans