Scaladocへのガイド

1. 序章

優れたドキュメントは、ソフトウェア開発における重要な要素です。 これにより、プロジェクトは長期的にはより保守しやすくなります。

Scaladoc は、Scalaソースコードで特別にフォーマットされたコメントを読み取り、コンパイルされたドキュメントを生成するドキュメント生成システムです。 これは、JavaのJavadocに似ています。

このチュートリアルでは、ScalaプロジェクトのコードにScaladocを追加する方法を学習します。 次に、追加されたコードからScaladocを生成します。 最後に、生成された出力を調べます。

2. コードへのScaladocの追加

Scaladocを追加するには、Scaladocコメントと呼ばれる特別なコメントブロックを使用できます。 Scaladocコメントの構造は、通常の複数行のコメントと非常によく似ていますが、主な違いは最初に余分なアスタリスクが付いていることです。

Scaladocを通常のコメントと比較してみましょう。

// This is a single line comment

/*
 * This is a regular multi-line comment
 */

/** This is a Scaladoc.
  * 
  */Copy

Scaladocコメントは、パッケージ、クラス、メソッド、特性、またはオブジェクトの上に置くことができます。 次のサブセクションでは、これらのオプションについて説明します。

2.1. パッケージ

パッケージのドキュメントには、パッケージの内容と含まれるクラスが含まれている必要があります。

まず、ファイルpackage.scalaにパッケージオブジェクトを作成する必要があります。 Scalaはこのオブジェクトを使用してドキュメントを生成します。

それでは、Scaladocをパッケージに追加しましょう。

package com.baeldung.scala

/** Package for Scaladoc tutorial.
  * Provides examples of Scaladoc and their elements such as tags and formattings.
  *
  * Class implemented in this package is [[com.baeldung.scala.scaladoc.IntervalTimer]].
  */
package object scaladoc {}Copy

このパッケージのクラス（この場合は IntervalTimer ）を二重角括弧表記で参照していることに注意してください。

2.2. クラス

クラスのドキュメントでは、クラスの機能とその使用方法を記述する必要があります。

IntervalTimerクラスのScaladocを作成しましょう。

package com.baeldung.scala.scaladoc

/** Represents a timer with interval.
  *
  * Specify how many `reps` desired for the timer and the `interval` between `reps`
  *
  * @constructor Create a timer with a specified `reps` and `interval`
  * @param reps Number of repetitions the timer will run.
  * @param interval Time between repetitions, in seconds. The default is 30 seconds.
  */
class IntervalTimer(val reps: Int, val interval: Int = 30) { }Copy

@constructor タグはコンストラクターの機能を説明するために使用され、@paramはコンストラクターで使用されるパラメーターを説明するために使用されます。

2.3. メソッド

メソッドのドキュメントでは、メソッドを使用した場合にそのメソッドが何をするかを説明する必要があります。

クラスIntervalTimerとそのScaladocのメソッドstartを作成しましょう。

/** Start this timer based on defined `reps` and `interval`.
  *
  * Print one message every second and another when each repetition is completed.
  * It cannot be stopped.
  */
def start(): Unit = {
  Array.range(1, reps + 1).foreach { rep =>
    Array.range(1, interval + 1).foreach { second =>
      Thread.sleep(1000)
      println(s"tic toc $second")
    }
    println(s"rep $rep is finished.")
  }
}Copy

メソッドの戻り値を定義する場合、@returnタグで何が返されるかを説明する必要があります。

/** Get total time, in seconds, that will be counted for this timer.
  *
  * @return The total number of seconds elapsed for this timer.
  */
def getTotalSeconds: Int = {
  interval * reps
}Copy

2.4. 特性

トレイトの概要と、トレイトを使用するクラスで指定する必要のあるメソッドを文書化する必要があります。可能であれば、トレイトを使用してクラスを作成する必要もあります。

特性肉食動物を見てみましょう：

/** Defines a meat eater.
  *
  * movement must be specified in class using this.
  * Used by [[com.baeldung.scala.scaladoc.TasmanianDevil]]
  */
trait Carnivore {
  def food: String = "meat"
  def movement: String
}Copy

2.5. オブジェクト

オブジェクトの場合、オブジェクトの目的を文書化する必要があります（例： ファクトリとして、暗黙のメソッド用）。 可能な場合は、そこで実装されているメソッドも文書化する必要があります。

ファクトリオブジェクトTasmanianDevilを見てみましょう。

package com.baeldung.scala.scaladoc

/** Factory for [[com.baeldung.scala.scaladoc.TasmanianDevil]] instances.
  *
  * Extends [[com.baeldung.scala.scaladoc.Carnivore]].
  */
object TasmanianDevil extends Carnivore {
  /** Creates a tasmanian devil with a given length.
    *
    * @param length the length of tasmanian devil in cm.
    */
  def apply(length: Int) = {}
  def movement: String = "Walk"
}Copy

3. フォーマットとタグ

Scaladocでは、 wikiスタイルのマークアップおよびタグを使用して、さまざまな種類の情報を伝達できます。

3.1. Wikiスタイルのマークアップ

wikiスタイルのマークアップの基本的なフォーマットを見てみましょう。

/** Formatting examples for Scaladoc:
  *
  * =Heading=
  * ==Sub-Heading==
  * `monospace`
  * ''italic text''
  * '''bold text'''
  * __underline__
  * ^superscript^
  * ,,subscript,,
  */Copy

リンクを作成するには、二重角かっこを使用できます。

/** [[entity link]], e.g. [[scala.collection.Seq]]
  * [[https://external.link External Link]],
  *   e.g. [[https://scala-lang.org Scala Language Site]]
  */Copy

ドキュメントにサンプルコードが必要な場合は、トリプル中括弧を使用してコードブロックを作成できます。

/** {{{
  * val example = 1
  * }}}
  */Copy

リストブロックは、同じスタイルとレベルの一連のリストアイテムであり、他のブロックスタイルからの中断はありません。 Scaladocでは、順序なしリストと順序付きリストの両方を作成できます。

順序付けられていないリストを作成するには、各アイテムの前に「 –」記号を使用できます。

/** Here is an unordered list:
  *
  *  - First item
  *  - Second item
  *    - Sub-item to the second
  *    - Another sub-item
  *  - Third item
  */Copy

順序付きリストが必要な場合は、「 1. 」、「 i。」、「 I. 」、または「a」を使用できます。 」は、さまざまな列挙スタイルを示します。

/** Here is an ordered list:
  *
  *  1. First numbered item
  *  1. Second numbered item
  *    i. Sub-item to the second
  *    i. Another sub-item
  *  1. Third item
  */Copy

どちらの場合も、前面のスペースを使用する必要があります。 より多くのスペースがサブレベルになります。

3.2. タグ

Scaladocにさまざまな種類の情報を含めるために、事前定義されたタグを使用できます。

• @authorはクラスの作成者を指定します
• @constructor は、コンストラクターの説明を提供します
• @param は、メソッドのパラメーターまたは必要な入力に関する有用な説明を提供します
• @return は、メソッドが返す、または返すことができるものの説明を提供します
• @since は、クラス、フィールド、またはメソッドがプロジェクトに追加されたバージョンを指定します
• @version は、%I % a nd %G% macrosで一般的に使用されるソフトウェアのバージョンを指定します
• @throws は、ソフトウェアが例外を予期する可能性がある場合をさらに説明するために使用されます
• @deprecated は、コードが非推奨になった理由、非推奨になった可能性がある場合、および代替手段について説明しています。
• @todo は、メソッドまたはクラスの保留中のアイテムを文書化するために使用されます

4. Scaladocの生成

コードにScaladocコメントを追加した後、sbtプロジェクトのディレクトリにあるコマンドラインからコメントを生成できます。

user@baeldung:~$ sbt docCopy

これにより、 target / scala- {version}/api/index.htmlにドキュメントが生成されます。

あそこに行って、Scaladocによって生成されるものを調べてみましょう。

ページの左側には、パッケージ用に作成したドキュメントが表示されています。 com.baeldung.scala.scaladoc。 右側には、Scaladocで利用可能なパッケージとクラスが表示されます。

IntervalTimer をクリックして、クラスのドキュメントの詳細を確認してみましょう。

ページの上部にクラスの説明が表示され、下部にコンストラクターとクラスメンバーが表示されます。 メソッドをクリックすると、説明が表示されます。

5. 結論

このチュートリアルでは、Scaladocを使用してScalaコードのドキュメントを作成する方法について説明しました。 また、コマンドラインからScaladocドキュメントを生成する方法を確認し、レンダリングされた結果を確認しました。

いつものように、このチュートリアルで使用されているすべての例は、GitHubでから入手できます。