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

[abgruszecki]

@julienrf I think for some usecases being able to define comments together with the parameters could be nice. I'm not sure if it's entirely easy to do though, given that we load docstrings from Tasty and that each docstring needs to be associated with a symbol.

@BarkingBad we definitely should leave out the validation part for now. Validating parameter names shouldn't be too difficult. Validating the types is an entirely different level of problem. Still, I'd like to leave the door open for implementing the feature later.

[BarkingBad]

I think this issue is no longer valid, as we have keyword in sigantures for using parameters and we decided not to have any validation for now and using params can be freely mixed with usual ones, so different section doesn't make sense anymore. I open new issue for Julien proposal here #11342