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

[Anthony F. <ant...@gm...>]

John --

Thanks for the feedback.  I think I have to respectively disagree, but it's
interesting to hear other points of view.  More detailed reply inline.

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
> <ant...@gm...> wrote:
> > Greetings.
> >
> > 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.  It wants to render it like so:
> >
> > retType
> > myFunction( Type1 arg1,
> >           Type2 arg2
> >           )
> >
> > In case that formatting gets mangled, you can see the difference in
> > this sample page, pointed out by PovAddict:
> >
> >
> http://www.stack.nl/~dimitri/doxygen/manual/examples/overload/html/class_test.html
> >    or: http://preview.tinyurl.com/avovthd
> >
> > I don't see any reason for this extra space, not even "const" or
> > similar.  After all, 0- and 1-arity functions don't get the extra
> > space.
>
> Hey there, perhaps in some cases the extra space is not needed, but,
> in others it adds something. Here is an example from the heavily
> customized but Doxygen-generated docs of my project (Haiku):
>
>
> http://api.haiku-os.org/classBArchivable.html#a256d5d912ec4e9a44be9054ee4d925f0
>
> It looks fine in this case to have the extra space and lines up the
> const with the parameter name instead of the parameter type.
>

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:

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

Either way, thanks for the reply.

Best regards,
Anthony Foiani