Scala3doc: No DRI found for query

[ekrich]

Compiler version

3.1.0

Minimized code

The trait Config has docs that point to ConfigValue.

* <p>
 * Convert a <code>Config</code> to a JSON or HOCON string by calling
 * [[#root root]] to get the [[ConfigObject]] and then call
 * [[ConfigValue!.render:String* render]]
 * on the root object, <code>myConfig.root.render</code>. There's also a variant
 * [[ConfigValue!.render(options:org\.ekrich\.config\.ConfigRenderOptions)* render(ConfigRenderOptions)]]
 * inherited from [[ConfigValue]] which allows you to control
 * the format of the rendered string. (See {@link ConfigRenderOptions}.) Note
 * that <code>Config</code> does not remember the formatting of the original
 * file, so if you load, modify, and re-save a config file, it will be
 * substantially reformatted.

Here is the generated docs: https://www.javadoc.io/doc/org.ekrich/sconfig_3/latest/index.html#org.ekrich.config.Config

Output

[info] Main Scala API documentation to /Users/eric/workspace/sconfig/sconfig/jvm/target/scala-3.1.0/api...
[info] Skipping unused scalacOptions: -deprecation, -feature
[warn] -- Warning: sconfig/shared/src/main/scala/org/ekrich/config/Config.scala:171:6 -
[warn] 171 |trait Config extends ConfigMergeable {
[warn] | ^
[warn] | No DRI found for query: ConfigValue!.render:String*
[warn] one warning found
[info] Main Scala API documentation successful.

Expectation

Works as it did in older versions. See https://www.javadoc.io/doc/org.ekrich/sconfig_2.11/latest/index.html#org.ekrich.config.Config

[pikinier20]

This problem is related to: #11119
We don't support method overloading in our member lookup like the old Scaladoc does. This bug shows that our query parser is also not 100% compliant with the old parser. I think this problem should be resolved together with method overloading support.

[abgruszecki]

@pikinier20 It wasn't really a goal to be 100% compliant with the old parser. If you take a look at https://dotty.epfl.ch/docs/usage/scaladoc/linking.html, the extensions mentioned there are technically incompatible with the old parser. Reg. overloading resolution, I more or less made a conscious choice not to support it the way Scaladoc2 supported it (based on regexes), because it seemed like a really hacky feature that wasn't even used in the community build.

[ekrich]

When I ported this from Java to Scala it was really hard to make the links work similar - really a nightmare. I am excited to see something better and easier for authors.

Now moving forward I could change the format and only publish Scala 3 docs but there needs to be a plan to move forward as many library authors have cross builds. For now I have it disabled so I can publish my project - others have done the same.

[bblfish]

could the meaning of DRI be written out in full? Looking at the error code in sbt I really had no clue where it came from.
see https://github.com/bblfish/httpSig/runs/5512261348?check_suite_focus=true#step:12:33

[abgruszecki]

@bblfish DRI is internal Scala3doc terminology. I agree we should avoid it in the error message, it's certainly not helpful. We could just say that we failed to resolve a query.

[bblfish]

@bblfish DRI is internal Scala3doc terminology. I agree we should avoid it in the error message, it's certainly not helpful. We could just say that we failed to resolve a query.

Thanks :-)
How do I go about resolving that error message?

[abgruszecki]

In your specific case, this one : run.cosy.http.headers.Rfc5234 ? If that's a valid identifier, then not looking it up is 100% a bug, please open an issue and someone will take a look at fixing it.

[ekrich]

I am not really seeing the Scaladoc docs here: https://dotty.epfl.ch/
These aren't the greatest and I had to search high and low for tips. https://docs.scala-lang.org/style/scaladoc.html

Has there been any discussion about links to overloads? I would like to get rid of the warning but then the doc links don't really point to the overloaded method so it is not really correct.

I found I can get rid of the warning by changing from
[[ConfigValue!.render:String render]] to
[[ConfigValue!.render():String render]] or
[[ConfigValue!.render render]] but then the links still point to
[[ConfigValue!.render(options:org\.ekrich\.config\.ConfigRenderOptions)* render(ConfigRenderOptions)]]

It would be nice if this was a bit easier.

[pikinier20]

@ekrich The problem with overloads is that it's not supported by the query parser which was rewritten in Scaladoc 3. So, we are always picking the same method ignoring the overload. See: #11119

The rewrite was necessary since the parser in Scaladoc 2 was very much coupled with the Scaladoc's internals and it wasn't an easy task to port it.