web-dev-qa-db-ja.com

scaladocのメソッドへのリンクを明確にする方法は？

Scalaクラスと オーバーロードされたメソッド を文書化しています。scaladocコメントでそれらを参照するときにそれらをどのように区別できますか？たとえば、

_/**
 * The most important method is [[Doc.foo]].
 */
object Doc {
  def foo[A]: A = throw new UnsupportedOperationException;
  def foo[A,B >: A](x: A): B = x;
}
_

_sbt doc_を実行します

Doc.scala：1：警告：リンクターゲット「Doc.foo」があいまいです。いくつかの（おそらくオーバーロードされた）メンバーがターゲットに適合します：

  • オブジェクトDocのメソッドfoo[A,B>:A](x:A):B [選択]
  • オブジェクトDocのメソッド_foo[A]:Nothing_

リンクに_foo[A,B >: A]_などを使用しても機能しません。

scalascala-2.10scaladocmethod-namesdisambiguation
32
Petr Pudlák

以下はScala 2.10でトリックを行うようです。

/**
 * The most important method is [[Doc.foo[A]:A*]].
 */

そしてここにscaladocが私に与えるいくつかのヒントがあります：

[warn] Quick crash course on using Scaladoc links
[warn] ==========================================
[warn] Disambiguating terms and types: Prefix terms with '$' and types with '!' in case both names are in use:
[warn]  - [[scala.collection.immutable.List!.apply class List's apply method]] and
[warn]  - [[scala.collection.immutable.List$.apply object List's apply method]]
[warn] Disambiguating overloaded members: If a term is overloaded, you can indicate the first part of its signature followed by *:
[warn]  - [[[scala.collection.immutable.List$.fill[A](Int)(⇒A):List[A]* Fill with a single parameter]]]
[warn]  - [[[scala.collection.immutable.List$.fill[A](Int,Int)(⇒A):List[List[A]]* Fill with a two parameters]]]
[warn] Notes: 
[warn]  - you can use any number of matching square brackets to avoid interference with the signature
[warn]  - you can use \. to escape dots in prefixes (don't forget to use * at the end to match the signature!)
[warn]  - you can use \# to escape hashes, otherwise they will be considered as delimiters, like dots.
27
Brian Hsu

Scaladocのドキュメントを調べて、複雑な署名の解決策（明らかにユニークな解決策）を見つけました。

  • 署名にスペースを使用しないでください
  • 引数名を使用する
  • 引数の型と戻り値の型の場合、すべてのドットの前に1つの円記号\を付けます。
  • 署名の最後にスター*を使用します
  • 完全な署名を使用します（あいまいな署名が提案されるため）。この手順はオプションです。*で終了する限り、署名を早期に停止できる場合があります。

例：

package org.my.stuff

class ReturnType

object Foo {
  class Bar {
    def lara(s: String): String = ???
    def lara(s: Foo.Bar): ReturnType= ???
  }
}

/** [[org.my.stuff.Foo$.Bar.lara(s:org\.my\.stuff\.Foo\.Bar):org\.my\.stuff\.ReturnType* The link to the right lara method]]
  */
object DocumentFooBarBingComplex {
}
8
Mikaël Mayer

これを機能させるのがいかに難しいか、そしてscaladoc自体のドキュメントが不足していることに私はまだ驚いています。いくつかの有用な例を期待して、scalaコードベース自体を検索することにしました。私が見つけた最高のものは https://github.com/scala/scala/blob /2.12.x/​​test/scaladoc/resources/links.scala 。うまくいけば、これはこれに出くわした他の誰かに役立つでしょう。

8
Steiny