Skip to content

Commit 1413c3a

Browse files
authored
Ambiguous link guidance (#2860)
1 parent cd240a8 commit 1413c3a

File tree

1 file changed

+57
-0
lines changed

1 file changed

+57
-0
lines changed

_overviews/scaladoc/for-library-authors.md

+57
Original file line numberDiff line numberDiff line change
@@ -239,6 +239,63 @@ The markup for list blocks looks like:
239239
- DRY - don't repeat yourself. Resist duplicating the method description in the
240240
`@return` tag and other forms of repetitive commenting.
241241

242+
## Resolving Ambiguous Links within Scaladoc Comments
243+
When two methods are indistinguishable from each other lexically, it can cause Scaladoc to
244+
report that there are ambiguous methods. As an example:
245+
246+
```scala
247+
import scala.collection.mutable.ListBuffer
248+
class bar {
249+
def foo(x: Int): Boolean = ???
250+
def foo(x: ListBuffer[Int], y: String): Int = ???
251+
}
252+
```
253+
254+
If one references `foo` via `[[foo]]`, then the Scaladoc will complain and offer both
255+
alternatives. Fixing this means elaborating the signature _enough_ so that it becomes unambiguous.
256+
There are a few things to be aware of in general:
257+
258+
* You must not use a space in the description of the signature: this will cause Scaladoc to
259+
think the link has ended and move onto its description.
260+
* You must fully qualify any types you are using: assume that you have written your program without
261+
any import statements!
262+
263+
Then, to disambiguate between objects and types, append `$` to designate a term name
264+
and `!` for a type name. Term names include members which are not types, such as `val`, `def`, and
265+
`object` definitions. For example:
266+
- `[[scala.collection.immutable.List!.apply class List's apply method]]` and
267+
- `[[scala.collection.immutable.List$.apply object List's apply method]]`
268+
269+
When dealing with ambiguous overloads, however, it gets a bit more complex:
270+
271+
* You must finish the signature, complete or otherwise, with a `*`, which serves as a wildcard
272+
that allows you to cut off the signature when it is umambiguous.
273+
* You must specify the names of the arguments and they must be _exactly_ as written in the
274+
function definition:
275+
- `[[bar.foo(Int)*]]` is **illegal** (no name)
276+
- `[[bar.foo(y:Int)*]]` is **illegal** (wrong name)
277+
- `[[bar.foo(x: Int)*]]` is **illegal** (space! Scaladoc sees this as `bar.foo(x:`)
278+
- `[[bar.foo(x:Int):Boolean]]` is **illegal** (no `*`)
279+
- `[[bar.foo(x:Int)*]]` is **legal** and unambiguous
280+
- `[[bar.foo(x:Int*]]` is **legal**, the `Int` is enough to disambiguate so no closing paren needed
281+
* The enclosing scope (package/class/object etc) of the method must use `.`, but within the arguments
282+
and return type `\.` must be used instead to fully qualify types:
283+
- `[[bar.foo(x:ListBuffer[Int],y:String)*]]` is **illegal** (no qualification on `ListBuffer`)
284+
- `[[bar.foo(x:scala.collection.mutable.ListBuffer[Int],y:String)*]]` is **illegal** (non-escaped dots!)
285+
- `[[bar\.foo(x:scala\.collection\.mutable\.ListBuffer[Int],y:String)*]]` is **illegal** (must not escape dots in the prefix)
286+
- `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int],y:String)*]]` is **legal**
287+
- `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int]*]]` is **legal**, the first argument is
288+
enough to disambiguate.
289+
* When generics are involved, additional square brackets may be used to avoid the
290+
signature accidentally closing the link. Essentially, the number of leading left brackets
291+
determines the number of right brackets required to complete the link:
292+
- `[[baz(x:List[List[A]])*]]` is **illegal** (it is read as `baz(x:List[List[A`)
293+
- `[[[baz(x:List[List[A]])*]]]` is **legal** (the `]]` is no longer a terminator, `]]]` is)
294+
295+
### Known Limitations
296+
* `#` syntax does not seem to be supported for parameters and return types.
297+
* Spaces cannot be escaped with `\ `, so `implicit` parameters seem not to be supported either.
298+
242299
## More details on writing Scaladoc
243300

244301
Further information on the formatting and style recommendations can be found in

0 commit comments

Comments
 (0)