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

[Yann, T. <TRE...@ca...>]

It would be more meaningful if the current option INTERNAL_DOCS was renamed
to MARK_INTERNAL_DOCS, and a new option HIDE_INTERNAL_DOCS was introduced.

For backward compatibility the INTERNAL_DOCS option could be deprecated,
generating a warning if used. Eventually it should be removed.

Trevor

-----Original Message-----
From: Glenn Maxey [mailto:gle...@vo...]
Sent: Tuesday, 27 November 2001 3:00 AM
To: Yann, Trevor; dox...@li...
Subject: RE: [Doxygen-users] Internal doco still output when
INTERNAL_DOCS is set to NO


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." 

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
> 
> 
> I have a source file that contains definitions that I would 
> like to suppress
> when generating user doco. It appears that I can mark the 
> declarations with
> \internal, and then use INTERNAL_DOCS to control the output.
> 
> I always see documentation entries, regardless of the setting of
> INTERNAL_DOCS. I expected that with INTERNAL_DOCS set to YES, 
> 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.
> 
> TIA,
> 
> Trevor
> 
> 
> Example source code
> -------------------
> 
> /** Number of PEM types that represent keys
>  *  @internal
>  */
> #define NUM_KEY_TYPES   8
> 
> Output with INTERNAL_DOCS set to NO
> -----------------------------------
> 
> #define NUM_KEY_TYPES  
>  
>    Number of PEM types that represent keys 
> 
> For internal use only. 
>  
> Output with INTERNAL_DOCS set to YES
> ------------------------------------
> #define NUM_CERT_TYPES  
>  
>    Number of PEM types that represent certificates 
>  
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>