doxygen-users

RE: [Doxygen-users] multiline /// comments

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

I use input filters. The FILTER_SOURCE_FILES tag and the INPUT_FILTER
tag in the project file can be used to specify a program that should be
invoked to filter for each input file. Doxygen uses the output that the
filter program writes to standard output.=20

I use use input filters to:
- Change comment styles from //! into /**...**/.=20
- Change class definitions into a format that is more standard for
Doxygen reporting.
- Change the @bug Doxygen command into @lim command that is defined in
the project file in the ALIASES section.=20
- Change program files (e.g., Perl, IVE) into a format that is more or
less recognized by Doxygen.Refer to the Doxygen documentation.

Attached is a simple Perl program that changes from //! comments to /**
... **/ comments. You'll easily be able to modify it to support ///
comments.

FWIW, /** ... **/ comments are more reliable because they are treated as
a block. This is important when the comments appear at the beginning of
a file and contain @file. When not in a block, Doxygen can sometimes
pick off individual //! comments from the file header and attach them to
the first valid code item it sees, like a #define.

The input filters mean than I can appease SW Engineering whims about
comment styles.

More tools to follow. The draft documentation is complete, but I need to
get it reviewed and approved.

Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
gle...@vo...


> -----Original Message-----
> From: Gedalia Pasternak [mailto:ge...@tu...]
> Sent: Thursday, January 17, 2002 9:24 AM
> To: dox...@li...
> Subject: [Doxygen-users] multiline /// comments
>=20
>=20
>=20
> Hello all,=20
>   After poking around the documentation for a while, I found=20
> that doxygen will concatate a multi-line /// comment into the=20
> brief description. I was wondering if there is any way to get=20
> doxygen to generate both the brief and the "more..." comments=20
> from multi-line comments. Like it would for /** comments. =20
> Our project leads really don't like the /** style comments,=20
> but I'm not thrilled with shoving all comments into the brief=20
> info block.
>  =20
>   Thanks, it's an awesome tool.
>=20
> -Gedalia Pasternak
>=20
> ---------------------------------------------------------------
> Graphics Engineer - www.TurbineGames.com	 =20
> AIM: gedaliap
> 781.407.4428
> ---------------------------------------------------------------
> Fight Entropy!!!  Fight Entropy!!!  Figth Etnropy! !
> iFgth Etnrop!y ! giFth tErno!py !  giFt htrEno!p y! --- Well maybe
> not...
>=20
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>=20

RE: [Doxygen-users] multiline /// comments

[Darren B. <db...@ga...>]

FYI, last I checked, multiline /// comments get cut off in unpredictable
ways for most comment types.  (This isn't a bug, as I recall that the
documentation doesn't claim to support such a multiline comment.)  You won't
get errors or warnings, so you have to examine the output manually.  Only
for describing a structure field does it seem to consistently work:

///
/// I don't trust this
/// comment here.
///
struct xxx {
    /// This works
    /// without problems.
    int y;
};

I've been avoiding /// comments in other contexts for several Doxygen
versions now.  Perhaps this has been fixed since, but I'd be on the lookout.

--Darren

-----Original Message-----
From: Gedalia Pasternak [mailto:ge...@tu...]
Sent: Thursday, January 17, 2002 8:24 AM
To: dox...@li...
Subject: [Doxygen-users] multiline /// comments



Hello all, 
  After poking around the documentation for a while, I found that doxygen
will concatate a multi-line /// comment into the brief description. I was
wondering if there is any way to get doxygen to generate both the brief and
the "more..." comments from multi-line comments. Like it would for /**
comments.  Our project leads really don't like the /** style comments, but
I'm not thrilled with shoving all comments into the brief info block.
  
  Thanks, it's an awesome tool.

-Gedalia Pasternak

---------------------------------------------------------------
Graphics Engineer - www.TurbineGames.com	  
AIM: gedaliap
781.407.4428
---------------------------------------------------------------
Fight Entropy!!!  Fight Entropy!!!  Figth Etnropy! !
iFgth Etnrop!y ! giFth tErno!py !  giFt htrEno!p y! --- Well maybe
not...

_______________________________________________
Doxygen-users mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users

RE: [Doxygen-users] multiline /// comments

[Gedalia P. <ge...@tu...>]

Hey thanks glenn, it seems pretty trivial to convert it over:
NEW_LINE: while (<>) {

   #########=20
   # Begin replacement of /// comments with /** ... **/ comments
   # This purposely does not do NEW_LINE or printing.
   #########=20
   if (/\/\/\//) {
      if ($comment_count =3D=3D 0){
         # first line of a comment block
         $comment_count++;
         $_ =3D~ s/\/\/\//\/\*\*/;
      } else {
         # Some line in the middle of a comment block.
         $comment_count++;
         ###
         # Changed to have middle stuff with no asterix.
         # $_ =3D~ s/\/\/\// \*\*/;
         ###
         $_ =3D~ s/\/\/\///;
      }
   } elsif ($comment_count > 0){
      # We were in a comment block; need to terminate it.
      $comment_count =3D 0;
      $_ =3D " \*\*\/\n" . $_ ;
   }
   ######### End Comment style change.
   =20
-Gedalia

[Doxygen-users] Forward declaration of enums

[Stephane R. <ste...@sy...>]

Hi,

here is my problem :

I'm using forward declaration of enums and classes in my classes.
With the enum, I've got a warning :
E:/tmp/dox/class.h:8 Warning: Member MyEnum of file class.h is not
documented.
But I have no warnings for forward declarations of classes
Is that normal ?
Is that a bug ?

TIA,

Stephane
////////////////////////////////////////////////////////////////////////////
/**
* \file class.h
* \brief Header file for the class class
*/
#ifndef _class_HeaderFile
#define _class_HeaderFile

enum MyEnum;
class MyOtherClass;

/**
* \class class
* \brief qqqqq
*/
class MyClass
{
public:

/**
 * \fn MyClass()
 * \brief ctor
 */
 MyClass()
 {};

/**
 * \fn ~MyClass()
 * \brief dtor
 */
 ~MyClass()
 {};

/**
 * \fn SetEnum(const enum MyEnum anEnum)
 * \brief set memeber
 * \param anEnum const enum MyEnum
 */
 void SetEnum(const enum MyEnum anEnum)
 {m_enum = anEnum;};


/**
 * \fn Enum()
 * \brief return member
 * \return MyEnum
 */
 MyEnum Enum()
 {return m_enum;};
private:
 /** the member */
 MyEnum m_enum;
};

#endif
////////////////////////////////////////////////////////////////////

Re: [Doxygen-users] Forward declaration of enums

[<br...@sh...>]

Quoting Stephane Routelous <ste...@sy...>:

> Hi,
> 
> here is my problem :
> 
> I'm using forward declaration of enums and classes in my classes.
> With the enum, I've got a warning :
> E:/tmp/dox/class.h:8 Warning: Member MyEnum of file class.h is not
> documented.
> But I have no warnings for forward declarations of classes
> Is that normal ?
> Is that a bug ?

Yes... In your code, and possibly your compiler. :-)

In general, you don't want to forward-declare enums. I'm not sure off the top 
of my head whether the syntax is even valid; even if it is, you shouldn't use 
it. C++ allows the size of an enumerant to depend on the range of values the 
enumeration must be able to hold. To derive this information, the compiler must 
be able to see the definition of the enumeration in each translation unit where 
the enumeration is used.

Braden

RE: [Doxygen-users] multiline /// comments

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

Hi Gedalia,

I realize that you probably grabbed the code out of context. In case you
didn't, I've included a couple of statements that makes your stuff more
reliable to others.

1) I initialize the $comment_count variable to 0 at the beginning.
Better safe than sorry that garbage was in memory and become the
starting point.

2) Don't forget the default fall-through which ends up printing the
modified $_ input line to the standard output. I purposely did not
include the print statement within this little "if" branch, because I
needed to have the ability to do other processing to the very same line,
like when I change from @bug to my user-defined @lim alias.

Glenn

> -----Original Message-----
> From: Gedalia Pasternak [mailto:ge...@tu...]
> Sent: Thursday, January 17, 2002 10:34 AM
> To: Glenn Maxey
> Cc: dox...@li...
> Subject: RE: [Doxygen-users] multiline /// comments

> Hey thanks glenn, it seems pretty trivial to convert it over:

=20
BEGIN {
   local ($comment_count) =3D 0;  # count if you're in the comments
somewhere.
}
=20
> NEW_LINE: while (<>) {
>=20
>    #########=20
>    # Begin replacement of /// comments with /** ... **/ comments
>    # This purposely does not do NEW_LINE or printing.
>    #########=20
>    if (/\/\/\//) {
>       if ($comment_count =3D=3D 0){
>          # first line of a comment block
>          $comment_count++;
>          $_ =3D~ s/\/\/\//\/\*\*/;
>       } else {
>          # Some line in the middle of a comment block.
>          $comment_count++;
>          ###
>          # Changed to have middle stuff with no asterix.
>          # $_ =3D~ s/\/\/\// \*\*/;
>          ###
>          $_ =3D~ s/\/\/\///;
>       }
>    } elsif ($comment_count > 0){
>       # We were in a comment block; need to terminate it.
>       $comment_count =3D 0;
>       $_ =3D " \*\*\/\n" . $_ ;
>    }
>    ######### End Comment style change.
 =20
   #########=20
   # Default Fall through
   #########=20
   print $_;

} # end of the NEW_LINE while loop  =20