RE: [Doxygen-users] Internal doco still output when INTERNAL_DOCS is set to NO

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

I agree with Trevor regarding how the @internal command works.

IMHO when INTERNAL_DOCS is NO and a code comment block contains
@internal, then that code comment block as well as the associated code
item should be surpressed from the output.

The way it works now is misleading. @internal merely appends the
statement "For Internal Use only."=20

I mean, if the developer or I know that something is only for internal
use, we can certainly write that into the code comments. That's a
no-brainer. It's only a few words longer than @internal. This way the
code is up to date.

However, if a code item is for internal use only, what we really need is
a mechanism to surpress the comment block (and code item) from appearing
in the output. This is what we think we are doing when we tag something
as @internal. This is not the case.

Glenn

> -----Original Message-----
> From: Yann, Trevor [mailto:TRE...@ca...]
> Sent: Sunday, November 25, 2001 9:43 PM
> To: dox...@li...
> Subject: [Doxygen-users] Internal doco still output when INTERNAL_DOCS
> is set to NO
>=20
>=20
> I have a source file that contains definitions that I would=20
> like to suppress
> when generating user doco. It appears that I can mark the=20
> declarations with
> \internal, and then use INTERNAL_DOCS to control the output.
>=20
> I always see documentation entries, regardless of the setting of
> INTERNAL_DOCS. I expected that with INTERNAL_DOCS set to YES,=20
> that I would
> see the documentation, along with "For internal use only". With
> INTERNAL_DOCS set to NO, I don't expect the item to be listed at all.
>=20
> TIA,
>=20
> Trevor
>=20
>=20
> Example source code
> -------------------
>=20
> /** Number of PEM types that represent keys
>  *  @internal
>  */
> #define NUM_KEY_TYPES   8
>=20
> Output with INTERNAL_DOCS set to NO
> -----------------------------------
>=20
> #define NUM_KEY_TYPES =20
> =20
>    Number of PEM types that represent keys=20
>=20
> For internal use only.=20
> =20
> Output with INTERNAL_DOCS set to YES
> ------------------------------------
> #define NUM_CERT_TYPES =20
> =20
>    Number of PEM types that represent certificates=20
> =20
>=20
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>=20