[Feature Request]: Should chpldoc put each argument on its own line?

[bradcray]

Summary of Feature

Description:

While reading through some documentation for library routines with many arguments today, as in BLAS:

I found myself thinking that it would be nice if chpldoc, by default at least, put each argument onto its own line—i.e., forced a line break after each comma, probably with the closing paren and return type on a line of its own, and potentially the where clause on a line of its own as well.

Then I wondered whether, for routines with a per-argument description in their chpldocumentation, we could also put that documentation onto the same line as the argument itself.

Is this a blocking issue with no known work-arounds? no

[lydia-duncan]

Spitballing, I could see a couple different ways to accomplish this:

• broadly (a flag to chpldoc that impacts all code)
• a chpldoc-specific attribute (or two if we wanted the where clause one to be separate) that can be attached to a specific function to make this more clear

I think I lean more towards the latter, but there's definitely a tradeoff in terms of user effort. If I went and implemented it today, I might try and add both to experiment with how our module documentation looks

[bradcray]

I think I'd take the approach of giving each argument its own line, with its description (if present) following it in a different font by default; and then have a per-subroutine attribute that permitted one to jump back to the current approach if desired. But as you say, seeing whether we think that generally improves our documentation or not before committing to it is the right thing to do.