[Doxygen-users] Documenting enums of an IDL file
Brought to you by:
dimitri
|
From: Francois St-A. <fst...@do...> - 2002-02-19 16:55:14
|
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
|