search

scala / scala3

The Scala 3 compiler, also known as Dotty.
https://dotty.epfl.ch
Apache License 2.0
5.88k stars 1.06k forks source link

Scaladoc reports broken links that aren't broken #16695

Closed alanbur closed 1 year ago

alanbur commented 1 year ago

Scaladoc version 3.2.1 -- Copyright 2002-2022, LAMP/EPFL

If a relative link is put in to a static doc which references the generated docs, it is incorrectly reported as broken. The link in the output works fine however.

[SomeClass](../foo/bar/SomeClass.html)

[warn] -- Warning: static_site/_docs/index.md -----------------------------------------
[warn] /home/foo/static_site/_docs/index.md: Unable to resolve link '../foo/bar/SomeClass.html

What's really needed is a proper way of referencing the generated class documentation from static doc files without including the entire class path, e.g. [[SomeClass]] rather than [[foo.bar.SomeClass]]. In fact the support for [[ ... ]]] references in static docs seems mostly broken,

alanbur commented 1 year ago

Thinking about it some more, perhaps the front matter directives should be extended to include import statements?

Also, full support for [[ ... ]] links that are compatible with doc comments in source files should be implemented, for example [[SomeClass descriptive text]] should work and currently doesn't.

ckipp01 commented 1 year ago

Hey @Dedelweiss I saw you opened a PR about this, but I figured it might be a good idea to discuss here a bit first because I have a few question that might help with the context for review.

What's really needed is a proper way of referencing the generated class documentation from static doc files without including the entire class path, e.g. [[SomeClass]] rather than [[foo.bar.SomeClass]].

Wouldn't we want to include the full classpath though? For example what happens in we have both a foo.bar.SomeClass and also a foo.baz.SomeClass? The only way to really differentiate them would be to include the fully qualified name. I think having SomeClass by itself here may cause a bit of confusion.

In fact the support for [[ ... ]]] references in static docs seems mostly broken,

Just to be clear, we're talking about [[...]] in the context of markdown leading to the api docs right? We're not talking about scaladocs that include [[...]]? If the the former, where is the feature even documented, I had no idea you could even do that.

julienrf commented 1 year ago

I agree that we should include the full classpath. I think it is fine to require a fully qualified name in static pages, but we may consider introducing a setting to set a package prefix if there is a high demand for it.