scaladocとグラフ

scaladoc

• apiドキュメントを出力してくれるツール
• 公式 https://docs.scala-lang.org/style/scaladoc.html

install(macの場合)

• scalaをインストールしたとき突っ込まれてる

> brew install scala
> which scaladoc
/usr/local/bin/scaladoc

usage

• scalaのプロジェクト上

scaladoc src/**/*.scala

ドキュメントにしたコード

/**
  * ヒーロー!コミックブックの主役
  */
trait Hero {
  /**
    * ヴィランをやっつけることで話が進む
    * @param viran
    */
  def defeatViran(viran: Viran): Unit

  /**
    * 良いことをするものがヒーロー
    */
  def goodActivity(): Unit
}

ドキュメントを見る

• scaladocを実行したディレクトリに出力されるindex.htmlを開く!
• Heroトレイトに対するコメントが表示されている
  
• Heroトレイトのドキュメント内ではメソッドへのコメントが表示されている！

図が欲しいなあ！

• ドキュメントを見ると丁寧にクラスの関係が出てきたりしている...
  

• 図とかでないかなぁ

ヘルプを見る

• グラフを出力するっぽいオプションがあるぞ‥！

> scaladoc -help
~略~
 -diagrams       Create inheritance diagrams for classes, traits and packages.
~略~

Try! グラフ出力

> scaladoc -graph src/**/*.scala

• めっちゃ怒られた‥下の文言がめっちゃでてきた
  • 図を作る時にエラーが起こっているらしい

Graphviz dot encountered an error when generating the diagram for: Hero

• めちゃくちゃ出てきた文言の最後の方にゴールのための一言が

Please note that graphviz package version 2.26 or above is required.

• graphvizってのが必要らしいな

graphviz

• brewでインストールできる

> brew install graphviz

• グラフを描画するためのパッケージ
  • wikiに日本語ページがある‥wiki

ReTry! グラフ出力

> scaladoc -graph src/**/*.scala

• とくにエラーメッセージは出ず‥！
• scaladocを見ると

• 感動！グラフが出てきた！

戦いは続く

• sbtからscaladocを作りたい

scaladoc from sbt

• sbtからコマンド１つで出来ました
• sbtプロジェクト上で

> sbt 
sbt> doc

• しかし、これで出力したドキュメントには図が乗っていない...

  • つまり実行オプションに-graphがないという状況なのだろう

• sbtのdocコマンドから呼ばれるscaladocにはbuild.sbtでscalacOptionsとして定義されたものが渡される

  • sourceコードリンク

• build.sbtを書き換える

build.sbt

~略~
scalacOptions in (Compile,doc) := Seq("-diagrams")
~略~

まとめ

• scalaをインストールしたとき付いてくるscaladocでapiドキュメントが出力できる
• クラス図をだしたかったら
  • graphvizをインストール
  • オプション-graphをつけてscaladocを実行する
• sbtから利用したいときはdocタスクを使う
  • scaladocのオプションを渡したいときはbuild.sbtでscalacOptionsに定義をしておく