How to document `using` parameters

[nicolasstucki]

Can we use @param to generate documentation for implicit parameters?
With somthig like the following:

/** ...
 *
 *  @param x: this is an explicit parameter
 *  @param ClassTag[X]: this is an implicit paramter
 */
def f[T](x: T)(using ClassTag[T]): Unit = ...

• Does this generate the correct docs?
• Do we need to worry about integration with other tools/IDEs?

[abgruszecki]

For now, the solution is to simply name the parameters. There is an analogous problem with linking to anonymous given definitions. We probably want to solve both of them simultaneously.

[nicolasstucki]

This issue was created after I tried that.

#10518 (comment)

I am not sure this is a good idea. These names are just noise. What is the problem with the docs if they are left out? Maybe we need to upgrade the doc tool to handle this gracefully?

[abgruszecki]

One of the problems that I saw is that we'd need to parse those types in the doctool, to see if they match.

But perhaps we don't need to do that? Perhaps we should identify the parameter simply based on the string representation of the type? This could help with givens as well.

[BarkingBad]

@abgruszecki are you working on this? Or can I try to fix this issue?

[abgruszecki]

@BarkingBad go ahead!

[abgruszecki]

@BarkingBad for clarity, we should try to at least render the using prefix in signatures in time for M3. Not rendering compiler-generated names is more difficult, so we shouldn't try too hard to have it by tomorrow.

[BarkingBad]

I hope the issue of keyword in signature was addressed in #10800. As it comes to problem with description, I think we don't have to bother with this problem at all. In Scala3doc for each @param we get key value relation that we embed into documentation. Since there is no additional linking/analysis of these, we can type just the symbolic name as we please.

Source: https://scala3doc.virtuslab.com/pr-master/testcases/api/tests/usings.html

What's your opinion about that? Can we close it?

[abgruszecki]

I think it'd be better if we'd have a separate section for context (using?) parameters. The documentation will look better if there's a separate section, I think, and it'll be possible to check if the parameter with the appropriate name/type actually exists.

[julienrf]

What do you think of documenting parameters directly, rather than in the scaladoc comment attached to their method/class definition?

E.g.:

/** A Foo */
case class Foo(
  /** An x */
  x: Int
)

def bar(
  /** A Bah */
  bah: Bah
)(using
  /** Context Quux */
  Quux
): Unit

I think this would be useful outside of using parameters, by the way.

[BarkingBad]

In my opinion inline comments would be too unmanageable for longer params descriptions.

As for separate section, it is really easy fix to do, and it makes sense. However, validation of name/type existance is a little bit more complex and we should discuss it how we would like to do that