[Doxygen-users] Documenting enums of an IDL file

[Francois St-A. <fst...@do...>]

Hello all,

Although I have used JavaDoc in Java development, I am quite new to =
using
Doxygen with IDL files. I'm hoping that someone on this list can help =
me
solve my problem generating API documentation for this ATL COM DLL IDL
(wow!) compiled with MS VC++ 6.0.

In a previous revision of the IDL file, I used to be able to get =
Doxygen to
generate documentation for enums in the IDL. At that point, the code =
looked
something like this:

	/**
	 * @mainpage
	 * Main page.
	 */

	import "oaidl.idl";
	import "ocidl.idl";

	[
		object,
		uuid(714D28AC-BF4C-49B8-9974-FA767789A962),
		dual,
		helpstring("IInstallerApiCtrl Interface"),
		pointer_default(unique)
	]

	/**
	 * This interface ...
	 */
	interface IInstallerApiCtrl : IDispatch
	{
		/**
		 * Result codes.
		 */
		typedef enum
		{

			/**
			 * The method executed successfully.
			 */
			SUCCESS =3D 0

		} ResultCode;

		/**
		 * Returns the number of un-configured U-520 series devices
in the
		 * Network Database.
		 *
		 * @retval psCount The number of un-configured U-520 series
devices.
		 *
		 * @return IInstallerApiCtrl::SUCCESS
		 *
		 * @see GetUnconfiguredU510Count
		 * @see GetUnconfiguredU520
		 * @see GetUnconfiguredU510
		 */
		[id(1), helpstring("method GetUnconfiguredU520Count")]
HRESULT
			GetUnconfiguredU520Count([out] short * psCount,
[out,retval] short * psResult);

	};


However, the code has now changed to:


	/**
	 * @mainpage
	 * Main page.
	 */

	/**
	 * Result codes.
	 */
	[uuid(714D28B1-BF4C-49B8-9974-FA767789A962)]
	enum ResultCode
	{

		/**
		 * The method executed successfully.
		 */
		SUCCESS =3D 0

	} ResultCode;

	import "oaidl.idl";
	import "ocidl.idl";

	[
		object,
		uuid(714D28AC-BF4C-49B8-9974-FA767789A962),
		dual,
		helpstring("IInstallerApiCtrl Interface"),
		pointer_default(unique)
	]

	/**
	 * This interface ...
	 */
	interface IInstallerApiCtrl : IDispatch
	{
		/**
		 * Returns the number of un-configured U-520 series devices
in the
		 * Network Database.
		 *
		 * @retval psCount The number of un-configured U-520 series
devices.
		 *
		 * @return IInstallerApiCtrl::SUCCESS
		 *
		 * @see GetUnconfiguredU510Count
		 * @see GetUnconfiguredU520
		 * @see GetUnconfiguredU510
		 */
		[id(1), helpstring("method GetUnconfiguredU520Count")]
HRESULT
			GetUnconfiguredU520Count([out] short * psCount,
[out,retval] short * psResult);

	};

Basically, the enum definitions are now defined outside of the =
interface and
have their own UIDs, instead of being defined within the interface. In =
this
configuration, Doxygen no longer generates documentation for the enums. =
I'm
not sure what is the best way to declare enums in an IDL file for an =
ATL COM
DLL. Programmers here have not much experience with this technology, =
but
they feel confident (from research on newsgroups) that this second =
approach
is the way to go. I am not debating this issue because I have no =
previous
experience with ATL COM DLLs and IDL files. But, if the file compiles =
and
seems to solve a problem the programmers had, that's great. But, I just =
need
to find a trick to get Doxygen to extract the enum comments and add =
these to
the generated docs.

I would love to get in touch with someone who has experienced similar
problems.

Regards,

Fran=E7ois St-Arnaud (Eng.), Senior Software Developer, =
fst...@do...
585 Charest Blvd E., 7th Floor, Quebec, QC, Canada, G1K 3J2
Tel: 418 681-8022/0006 x243  Fax: 681-8015
Visit our new website and see the benefits of our PowerBus(tm) =
Technology @
www.domosys.com
We've moved!  Please update your contact info for us, click for more =
info