Re: [Doxygen-develop] don't put closing parenthesis on its own line

[John S. <jsc...@gm...>]

On Wed, Feb 27, 2013 at 3:57 PM, Anthony Foiani
<ant...@gm...> wrote:
> On Wed, Feb 27, 2013 at 1:22 PM, John Scipione <jsc...@gm...> wrote:
>> On Tue, Feb 26, 2013 at 2:32 AM, Anthony Foiani
>> > I don't know if it is intentional or not, but I found that the current
>> > Doxygen output for multiple (2-or-more) argument functions to be
>> > sub-optimal.
>> Hey there, perhaps in some cases the extra space is not needed, but,
>> in others it adds something.
> I guess I still find that inconsistent.  Why does a 2-arity function require
> that extra space, when a 1-arity function doesn't?
>
> Your example demonstrates the issue:
>
> status_t BArchivable::Archive ( BMessage * into,
>                                 bool       deep = true
>                               )            const [virtual]
>
> static BArchivable * BArchivable::Instantiate ( BMessage * archive )
> [static]
>
> Why does a 1-arity function get the "snug" parenthesis, while the 2-arity
> gets the extra line?  To consistently apply your look, the second one should
> look like:
>
> static BArchivable * BArchivable::Instantiate ( BMessage * archive
>                                               )            [static]
>
> Not my cup of tea at all.  :(
>
> Out of curiosity, what does the corresponding original source code look
> like?  I can't recall having ever seen any C++ or Java that looked anything
> like that, and I suspect that I am trying to get my docs to look more like
> my code in this regard.  I've seen all these styles, and used most of them
> at one time or another:

The line from the header file looks like this:

virtual status_t Archive(BMessage* into, bool deep = true) const;

all in one line. In Doxygen this gets translated into multiple lines
for style reasons.

> retType function( argType arg, argType arg ) modifier;
>
> retType function( argType arg,
>                   argType arg ) modifier;
>
> retType
> function( argType arg, argType arg ) modifier;
>
> retType
> function( argType arg,
>           argType arg ) modifier;
>
> retType
> function(
>     argType arg,
>     argType arg
> ) modifier;
>
> I don't think I've never seen anything like the "align modifiers with arg
> names".
>
> (Then again, I know lots of people who are in love with the "comma at the
> beginning of the line" style for arguments, and that drives me completely up
> the wall.  Tastes vary.  :)
>
>>
>> If you really want this to work though you'd need to add a colspan="2"
>> to that ending <td> for only the last parameter. It would look like
>> this:
>>
>> +    t << "          <td colspan=\"2\">";
>>
>> So that the const, virtual, etc. specifiers would span both the param
>> type and param name columns. Make that change and I could get behind
>> this patch.
>
> Except I *don't* want them lined up with the arg list, because they're not
> arguments: they're something else.
>
> If you feel they *should* be aligned with the arg list, then I would expect
> you'd request the same alignment for 1-arity functions as well.
>
> I think that I'll either respin the patch to make this a config option, or
> just use my patched build.  I don't see any reason at all for the
> inconsistency...

My suggestion to use colspan="2" was so that if you had a bunch of
specifiers const, virtual, static, etc. they wouldn't wrap at the end
of the column name. My suggestion would basically make it look like
your last example, sorta like this

retType function( argumentType argName1,
                          argumentType argName2 = NULL
                        ) specifier1 [specifier2] [specifier3]

If you don't have the colspan="2" you'll get this instead:

retType function( argumentType argName1,
                          argumentType argName2 = NULL
                        ) specifier1
                          [specifier2]
                          [specifier3]

because the specifiers will wrap with argumentType.

I guess if it's not your cup of tea there's not a lot that I can do
about it. Doxygen is just not designed to fit everyones particular
personal style. If it had a template system to customize the output...
one can dream.

John Scipione
PS: I'm not a doxygen developer, just a user, so, take what I say with
a grain of salt.