How is Scaladoc linking supposed to work?

[Simon Ochsenreither]

I'm a bit puzzled whether this is intentional behavior or not:

• If I'm in package foo.bar and type Baz is package foo, a scaladoc link to Baz works without any imports:

package foo.bar

/** [[Baz]] */ // works, even if Baz is never in scope.

• But if a link isn't found, an import can't fix it: I'm in package foo,  and want to link to Biz in package foo.bar it doesn't work:

package foo

import foo.bar.Biz

/** [[Biz]] */ // Doesn't work?

/** [[bar.Biz]] */ // This does ...

Can anyone comment on whether this is something that should be fixed?

[Vlad Ureche]

Hi Simon,

The link resolution is not done by the name resolution phase in scalac (which obeys imports) but by a custom name resolution tool.
I agree it would be less surprising if it would be done with name resolution, but technical limitations did not allow us to do it.

Pinging @Felix who is working on dottydoc: it would be the most intuitive if you used the name resolution from dotty to resolve links!

Instead, link resolution visits the current entity, its members, and then goes down the parent chain. So what you're seeing is expected:

1) Baz is found in package foo since the resolution has gone down the parent chain from package foo.bar to package foo

2) An import won't fix a broken link, but it's possible to add enough qualification to allow the resolution to succeed. In particular, bar.Biz does exist in package foo. So does foo.bar.Biz in package __root__, to which you can get by navigating down the parent chain.

Let's see if dottydoc will be able to use name resolution, and if so, how badly it will break existing documentation...

HTH,

Vlad

--
You received this message because you are subscribed to the Google Groups "scala-internals" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scala-interna...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Simon Ochsenreither]

Thanks for the information!

I have a project that was ported from Java which causes hundreds of warnings because of this difference (how many exactly is unkown because the scaladoc tool only reports one error per documentation block – I think there are at least a few thousand errors).

I hope Felix has some success stories with his work, then I can test it, and report back!