@@ -239,6 +239,63 @@ The markup for list blocks looks like:
239
239
- DRY - don't repeat yourself. Resist duplicating the method description in the
240
240
` @return ` tag and other forms of repetitive commenting.
241
241
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
+
242
299
## More details on writing Scaladoc
243
300
244
301
Further information on the formatting and style recommendations can be found in
0 commit comments