Scaladoc shows parameters out of order

[alvinj]

Compiler version

3.0.0-RC1

Minimized code

The code I’m interested in is this scaladoc:

/**
 * Newton’s Method for solving equations.
 * @param fx The equation to solve.
 * @param fxPrime The derivative of `fx`.
 * @param x An initial “guess” for the value of `x`.
 * @param tolerance Stop iterating when the iteration values are 
          within this tolerance.
 * @todo Check that `f(xNext)` is greater than a second tolerance value.
 * @todo Check that `f'(x) != 0`
 */
def newtonsMethod(
    fx: Double => Double,
    fxPrime: Double => Double,
    x: Double,
    tolerance: Double
): Double = ???

Output

The Scaladoc that’s generated from the scaladoc command shows the tolerance and x fields in the wrong (opposite) order, as shown in the attached image.

Expectation

I expect the fields to be displayed in the order I define them in the scaladoc:

• fx
• fxPrime
• x
• tolerance

[som-snytt]

The parameters are shown in alphabetical order.

This ticket requests "doc order" (order of the param tags), but I think the first expectation is "code order", or normal param order.

Maybe after fulfilling the natural expectation, a --param-order:natural|name|tag option would be (marginally) useful.

(One could imagine a codebase with a method taking a large number of params, and natural order is not helpful.) (I was thinking automated code or a macro expansion, but another example is Scaladoc.Args.)

[alvinj]

I think since I’m the only one who showed an interest in this in 2+ years, it’s safe to say that you can close this issue if you’d like. :)

(Also, I shouldn’t have written that the fields were listed in the “wrong” order, it just wasn’t the order I expected.)

[som-snytt]

@alvinj thanks for clarifying. Now that I've spent a few hours learning (some) code, I'll take some sort of action. (Unintended pun on "sort".) Javadoc is in what I call "natural" order. It wasn't obvious to me at first that the current sort is alphabetical, as though we subconsciously name parameters that sort: i, j; x, y; elem1, elem2, etc. Cf addString.

My other idea is to make param names clickable to either scroll to or highlight the param doc. I like that idea best, as it is unfussy.

The other dimension is that it does zero validation on the param doc, which is clearly wrong. I'll do that much, at a minimum.

Edit: I only just noticed that the ticket is marked enhancement, so probably they came to the conclusion that alpha order was as intended, or at least (as I discovered) not trivial to change.

[alvinj]

@som-snytt Yes, I saw the enhancement part as well, and without a lot of other people commenting on this, I thought that was right. And it’s interesting that it doesn’t do the validation you mentioned! Thanks again!