From 0084ffa57e229448f1fc43eec265119616793956 Mon Sep 17 00:00:00 2001 From: Jamie Willis Date: Sun, 9 Jul 2023 22:57:21 +0100 Subject: [PATCH 1/4] Added the crash course directly from compiler, needs fixing --- _overviews/scaladoc/for-library-authors.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/_overviews/scaladoc/for-library-authors.md b/_overviews/scaladoc/for-library-authors.md index 332cbffd17..82faa8e360 100644 --- a/_overviews/scaladoc/for-library-authors.md +++ b/_overviews/scaladoc/for-library-authors.md @@ -239,6 +239,19 @@ The markup for list blocks looks like: - DRY - don't repeat yourself. Resist duplicating the method description in the `@return` tag and other forms of repetitive commenting. +## Resolving Ambiguous Links within Scaladoc Comments + +Disambiguating terms and types: Suffix terms with '$' and types with '!' in case both names are in use: + - `[[scala.collection.immutable.List!.apply class List's apply method]]` and + - `[[scala.collection.immutable.List$.apply object List's apply method]]` +Disambiguating overloaded members: If a term is overloaded, you can indicate the first part of its signature followed by *: + - `[[[scala.collection.immutable.List$.fill[A](Int)(=> A):List[A]* Fill with a single parameter]]]` + - `[[[scala.collection.immutable.List$.fill[A](Int, Int)(=> A):List[List[A]]* Fill with a two parameters]]]` +Notes: + - you can use any number of matching square brackets to avoid interference with the signature + - you can use `\\.` to escape dots in prefixes (don't forget to use * at the end to match the signature!) + - you can use `\\#` to escape hashes, otherwise they will be considered as delimiters, like dots. + ## More details on writing Scaladoc Further information on the formatting and style recommendations can be found in From ba01ce6ea288417691368f6e6a8a6d0edb5a8933 Mon Sep 17 00:00:00 2001 From: Jamie Willis Date: Sun, 9 Jul 2023 23:51:34 +0100 Subject: [PATCH 2/4] improved with more examples and correct info --- _overviews/scaladoc/for-library-authors.md | 61 ++++++++++++++++++---- 1 file changed, 52 insertions(+), 9 deletions(-) diff --git a/_overviews/scaladoc/for-library-authors.md b/_overviews/scaladoc/for-library-authors.md index 82faa8e360..c90107bb7c 100644 --- a/_overviews/scaladoc/for-library-authors.md +++ b/_overviews/scaladoc/for-library-authors.md @@ -240,17 +240,60 @@ The markup for list blocks looks like: `@return` tag and other forms of repetitive commenting. ## Resolving Ambiguous Links within Scaladoc Comments - -Disambiguating terms and types: Suffix terms with '$' and types with '!' in case both names are in use: +When two methods are indistinguishable from each other lexically, it can cause Scaladoc to +report that there are ambiguous methods. As an example: + +```scala +import scala.collection.mutable.ListBuffer +class bar { + def foo(x: Int): Boolean = ??? + def foo(x: ListBuffer[Int], y: String): Int = ??? +} +``` + +If one references `foo` via `[[foo]]`, then the Scaladoc will complain and offers up both +alternatives. Fixing this means elaborating the signature _enough_ so that it becomes unambiguous. +There are a few things to be aware of in general: + +* You must not use a space in the description of the signature: this will cause Scaladoc to + think the link has ended and move onto its description. +* You must fully qualify any types you are using: assume that you have written your program without + any import statements! + +Then, to disambuate between objects and types (where both are in use), postfix with a `$` for objects +and `!` for types. For example: - `[[scala.collection.immutable.List!.apply class List's apply method]]` and - `[[scala.collection.immutable.List$.apply object List's apply method]]` -Disambiguating overloaded members: If a term is overloaded, you can indicate the first part of its signature followed by *: - - `[[[scala.collection.immutable.List$.fill[A](Int)(=> A):List[A]* Fill with a single parameter]]]` - - `[[[scala.collection.immutable.List$.fill[A](Int, Int)(=> A):List[List[A]]* Fill with a two parameters]]]` -Notes: - - you can use any number of matching square brackets to avoid interference with the signature - - you can use `\\.` to escape dots in prefixes (don't forget to use * at the end to match the signature!) - - you can use `\\#` to escape hashes, otherwise they will be considered as delimiters, like dots. + +When dealing with ambiguous overloads, however, it gets a bit more complex: + +* You must finish the signature, complete or otherwise, with a `*`, which serves as a wildcard + that allows you to cut off the signature when it is umambiguous. +* You must specify the names of the arguments and they must be _exactly_ as written in the + function definition: + - `[[bar.foo(Int)*]]` is **illegal** (no name) + - `[[bar.foo(y:Int)*]]` is **illegal** (wrong name) + - `[[bar.foo(x: Int)*]]` is **illegal** (space! Scaladoc sees this as `bar.foo(x:`) + - `[[bar.foo(x:Int):Boolean]]` is **illegal** (no `*`) + - `[[bar.foo(x:Int)*]]` is **legal** and unambiguous + - `[[bar.foo(x:Int*]]` is **legal**, the `Int` is enough to disambiguate so no closing paren needed +* The enclosing scope (package/class/object etc) of the method must use `.`, but within the arguments + and return type `\.` must be used instead: + - `[[bar.foo(x:ListBuffer[Int],y:String)*]]` is **illegal** (no qualification on `ListBuffer`) + - `[[bar.foo(x:scala.collection.mutable.ListBuffer[Int],y:String)*]]` is **illegal** (non-escaped dots!) + - `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int],y:String)*]]` is **legal** + - `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int]*]]` is **legal**, the first argument is + enough to disambiguate. +* When generics are involved, any number of additional square brackets may be used to avoid the + signature accidentally closing the link: + - `[[baz(x:List[List[A]])*]]` is **illegal** (it is read as `baz(x:List[List[A`) + - `[[[baz(x:List[List[A]])*]]]` is **legal** (the `]]` is no longer a terminator, `]]]` is) + +Current holes: + * it is unclear how `#` is to be handled within argument/return types: `#` doesn't seem to work + and neither does `\#`: there are no tests for this, so perhaps this is a bug. + * it is unclear how to avoid a need for space after `implicit`, again, no tests for this: spaces + cannot be escapes with `\ `. ## More details on writing Scaladoc From 828fe04f310b4cefbd3e604506f94e7e1e923644 Mon Sep 17 00:00:00 2001 From: Jamie Willis Date: Mon, 10 Jul 2023 00:00:30 +0100 Subject: [PATCH 3/4] typo --- _overviews/scaladoc/for-library-authors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_overviews/scaladoc/for-library-authors.md b/_overviews/scaladoc/for-library-authors.md index c90107bb7c..31dd4442a2 100644 --- a/_overviews/scaladoc/for-library-authors.md +++ b/_overviews/scaladoc/for-library-authors.md @@ -293,7 +293,7 @@ Current holes: * it is unclear how `#` is to be handled within argument/return types: `#` doesn't seem to work and neither does `\#`: there are no tests for this, so perhaps this is a bug. * it is unclear how to avoid a need for space after `implicit`, again, no tests for this: spaces - cannot be escapes with `\ `. + cannot be escaped with `\ `. ## More details on writing Scaladoc From 0f7e11ad458dd150569308893f70754bcf8ee3e0 Mon Sep 17 00:00:00 2001 From: Jamie Willis Date: Mon, 10 Jul 2023 08:25:44 +0100 Subject: [PATCH 4/4] Resolved @som-syntt's comments, thanks! --- _overviews/scaladoc/for-library-authors.md | 23 +++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/_overviews/scaladoc/for-library-authors.md b/_overviews/scaladoc/for-library-authors.md index 31dd4442a2..621861450e 100644 --- a/_overviews/scaladoc/for-library-authors.md +++ b/_overviews/scaladoc/for-library-authors.md @@ -251,7 +251,7 @@ class bar { } ``` -If one references `foo` via `[[foo]]`, then the Scaladoc will complain and offers up both +If one references `foo` via `[[foo]]`, then the Scaladoc will complain and offer both alternatives. Fixing this means elaborating the signature _enough_ so that it becomes unambiguous. There are a few things to be aware of in general: @@ -260,8 +260,9 @@ There are a few things to be aware of in general: * You must fully qualify any types you are using: assume that you have written your program without any import statements! -Then, to disambuate between objects and types (where both are in use), postfix with a `$` for objects -and `!` for types. For example: +Then, to disambiguate between objects and types, append `$` to designate a term name +and `!` for a type name. Term names include members which are not types, such as `val`, `def`, and +`object` definitions. For example: - `[[scala.collection.immutable.List!.apply class List's apply method]]` and - `[[scala.collection.immutable.List$.apply object List's apply method]]` @@ -278,22 +279,22 @@ When dealing with ambiguous overloads, however, it gets a bit more complex: - `[[bar.foo(x:Int)*]]` is **legal** and unambiguous - `[[bar.foo(x:Int*]]` is **legal**, the `Int` is enough to disambiguate so no closing paren needed * The enclosing scope (package/class/object etc) of the method must use `.`, but within the arguments - and return type `\.` must be used instead: + and return type `\.` must be used instead to fully qualify types: - `[[bar.foo(x:ListBuffer[Int],y:String)*]]` is **illegal** (no qualification on `ListBuffer`) - `[[bar.foo(x:scala.collection.mutable.ListBuffer[Int],y:String)*]]` is **illegal** (non-escaped dots!) + - `[[bar\.foo(x:scala\.collection\.mutable\.ListBuffer[Int],y:String)*]]` is **illegal** (must not escape dots in the prefix) - `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int],y:String)*]]` is **legal** - `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int]*]]` is **legal**, the first argument is enough to disambiguate. -* When generics are involved, any number of additional square brackets may be used to avoid the - signature accidentally closing the link: +* When generics are involved, additional square brackets may be used to avoid the + signature accidentally closing the link. Essentially, the number of leading left brackets + determines the number of right brackets required to complete the link: - `[[baz(x:List[List[A]])*]]` is **illegal** (it is read as `baz(x:List[List[A`) - `[[[baz(x:List[List[A]])*]]]` is **legal** (the `]]` is no longer a terminator, `]]]` is) -Current holes: - * it is unclear how `#` is to be handled within argument/return types: `#` doesn't seem to work - and neither does `\#`: there are no tests for this, so perhaps this is a bug. - * it is unclear how to avoid a need for space after `implicit`, again, no tests for this: spaces - cannot be escaped with `\ `. +### Known Limitations + * `#` syntax does not seem to be supported for parameters and return types. + * Spaces cannot be escaped with `\ `, so `implicit` parameters seem not to be supported either. ## More details on writing Scaladoc