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