doxygen-develop

[Doxygen-develop] [PATCH] Support for C++ comments next to arguments of macro function

[Christian S. <sch...@cr...>]

Hi,

please consider the attached patch for git, which allows code input like this 
to be processed correctly:

 #ifndef DECLARE_ENUM
 # define DECLARE_ENUM(type, ...) enum type { __VA_ARGS__ }
 #endif

 DECLARE_ENUM(Foo_t,
     foo1 = 0x000000001, ///< First comment.
     foo2 = 22, ///< Second comment.
     foo3
 );

The current general behavior of dropping all new line characters on macro 
expansion is preserved. Accordingly those C++ comments are automatically 
rewritten as inline C comments instead.

Best regards,
Christian Schoenebeck

Re: [Doxygen-develop] [PATCH] Support for C++ comments next to arguments of macro function

[Albert <alb...@gm...>]

Dear Christian,

What happens in case of multi-line inline comments?
E.g.:
DECLARE_ENUM(Foo_t,
     foo1 = 0x000000001, ///< First comment.
                                    ///< continuation of first comment
     foo2 = 22, ///< Second comment.
                    ///< continuation of second comment
     foo3
 );

Best Regards,

Albert

<http://www.avg.com/email-signature?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
Virus-free.
www.avg.com
<http://www.avg.com/email-signature?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
<#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>

On Sun, Dec 10, 2017 at 7:10 PM, Christian Schoenebeck via Doxygen-develop <
dox...@li...> wrote:

> Hi,
>
> please consider the attached patch for git, which allows code input like
> this
> to be processed correctly:
>
>  #ifndef DECLARE_ENUM
>  # define DECLARE_ENUM(type, ...) enum type { __VA_ARGS__ }
>  #endif
>
>  DECLARE_ENUM(Foo_t,
>      foo1 = 0x000000001, ///< First comment.
>      foo2 = 22, ///< Second comment.
>      foo3
>  );
>
> The current general behavior of dropping all new line characters on macro
> expansion is preserved. Accordingly those C++ comments are automatically
> rewritten as inline C comments instead.
>
> Best regards,
> Christian Schoenebeck
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Doxygen-develop mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-develop
>
>

Re: [Doxygen-develop] [PATCH] Support for C++ comments next to arguments of macro function

[Christian S. <sch...@cr...>]

On Sonntag, 10. Dezember 2017 19:50:06 CET Albert wrote:
> Dear Christian,
> 
> What happens in case of multi-line inline comments?
> E.g.:
> DECLARE_ENUM(Foo_t,
>      foo1 = 0x000000001, ///< First comment.
>                                     ///< continuation of first comment
>      foo2 = 22, ///< Second comment.
>                     ///< continuation of second comment
>      foo3
>  );

Internally that example macro would first be expanded by the lexer like this:

enum Foo_t {     foo1 = 0x000000001, /**< First comment. */                                    /**< continuation of first comment */     foo2 = 22, /**< Second comment. */                    /**< continuation of second comment */     foo3 };

Everything in one line at this point.

And in the final (i.e. html) document the enum member "foo1" for example would then end up with the following explanation text (tested):

---------------------------
First comment
[NEW-LINE]
continuation of first comment
---------------------------

Best regards,
Christian Schoenebeck

Re: [Doxygen-develop] [PATCH] Support for C++ comments next to arguments of macro function

[Albert <alb...@gm...>]

Dear Christian,

Not sure if this is wanted., especially when the second part of the comment
spans multiple lines. In this case we see now multiple lines in the comment
although the intention, by the documentation writer, was just one block but
this could lead to an incredible long line in the original source.

Albert

<http://www.avg.com/email-signature?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
Virus-free.
www.avg.com
<http://www.avg.com/email-signature?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
<#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>

On Sun, Dec 10, 2017 at 8:14 PM, Christian Schoenebeck via Doxygen-develop <
dox...@li...> wrote:

> On Sonntag, 10. Dezember 2017 19:50:06 CET Albert wrote:
> > Dear Christian,
> >
> > What happens in case of multi-line inline comments?
> > E.g.:
> > DECLARE_ENUM(Foo_t,
> >      foo1 = 0x000000001, ///< First comment.
> >                                     ///< continuation of first comment
> >      foo2 = 22, ///< Second comment.
> >                     ///< continuation of second comment
> >      foo3
> >  );
>
> Internally that example macro would first be expanded by the lexer like
> this:
>
> enum Foo_t {     foo1 = 0x000000001, /**< First comment. */
>                     /**< continuation of first comment */     foo2 = 22,
> /**< Second comment. */                    /**< continuation of second
> comment */     foo3 };
>
> Everything in one line at this point.
>
> And in the final (i.e. html) document the enum member "foo1" for example
> would then end up with the following explanation text (tested):
>
> ---------------------------
> First comment
> [NEW-LINE]
> continuation of first comment
> ---------------------------
>
> Best regards,
> Christian Schoenebeck
>
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Doxygen-develop mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-develop
>

Re: [Doxygen-develop] [PATCH] Support for C++ comments next to arguments of macro function

[Christian S. <sch...@cr...>]

On Sonntag, 10. Dezember 2017 20:25:16 CET Albert wrote:
> Dear Christian,
> 
> Not sure if this is wanted., especially when the second part of the comment
> spans multiple lines. In this case we see now multiple lines in the comment
> although the intention, by the documentation writer, was just one block but
> this could lead to an incredible long line in the original source.

Not sure if we have a misapprehension here: the output I showed to you with 
that many spaces is just temporary data right at the point where the macro got 
expanded internally by the lexer. Those superfluous spaces will be filtered out 
immediately right after that point and will end up nowhere; so you will 
neither find those spaces anywere in the generated documentation, nor in the 
referenced sources.

The part where you criticism is valid though, is that this patch does not 
merge the individual comment lines from your example, and that you might thus 
end up with more line feeds in the generated member explanation text than 
originally desired by the author. So this:

DECLARE_ENUM(Foo_t,
    foo1 ///< 1st comment.
         ///< 2nd comment.
         ///< 3rd comment.
);

becomes this:

"1st comment.\n2nd comment.\n3rd comment."

instead of:

"1st comment. 2nd comment. 3rd comment."

But to be really honest with you: this is really a minor issue IMO that can 
still be addressed, compared to the current situation. Just to make this 
clear: right now with latest git master head, C++ comments in the latter 
example end up like this after the preprocessor stage of Doxygen:

----------------------------------------------
///< 1st comment.
///< 2nd comment.
///< 3rd comment.

enum Foo_t { foo1 }
----------------------------------------------

And accordingly you currently end up with no documentation at all for any of 
those enum members, and additionall you might even end up with those orphaned 
text blocks to be sticked to wrong (preceding the enum) code blocks instead.

Best regards,
Christian Schoenebeck