Senseiでドキュメントリンクを活用する

新しいライブラリの学習や、チーム内でベストプラクティスを共有する際、ドキュメントの作成やサンプルコードの準備が大きな課題となります。

多くの場合、小さなサンプルプロジェクトを作成しても、実際のコードを書いている最中にそれを参照することはほとんどありません。

サンプルコードやオンラインの解説ページに直接リンクを貼り、必要に応じてURLから詳細な説明を確認できれば非常に便利だと常々感じていました。

JavaにはJavaDocコメントがあり、@seeアノテーションを使用できます：

/**
 * @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Junit 5 Annotation docs</a>
 */

サードパーティ製ライブラリでこのようなJavaDocが提供されていると、IntelliJのクイックドキュメント機能から詳細な例にアクセスできるため、非常に役立ちます。

しかし、コメントはコードほど頻繁に更新されないのが現実です。また、Web上のドキュメントはライブラリのメンテナンスとは切り離されており、別のチームが管理していることも珍しくありません。

Senseiの活用方法

Senseiを使えば、ライブラリのアノテーションやメソッドを検出し、Wikiや外部のチュートリアルサイトにある詳細なドキュメントへのリンクを表示させることができます。

例として、JUnitの @Test アノテーションを使用してみます。

JavaDocは非常に詳細で、クイックドキュメントビューでもアノテーションの使い方が説明されています。

しかし、公式サイトのドキュメントの方が読みやすく、より多くのサンプルが掲載されていることも少なくありません。

チームで新しいライブラリを学習し始める際、推奨されるチュートリアル集があると非常に便利です。

Senseiには goto アクションがあり、これを使ってURLを開くことができます。チームにとって有益な外部サイトやサンプルコードへのリンクを直接提供できるのです。

Goto URLの実装

これを実装するには、まずJUnitの@Testアノテーションに一致する検索条件を作成します。

search:
   annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.api.Test"

次に、役立つURLごとにgotoアクションを追加します。

例：

• https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations
• https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods

以下の例では、1つのアクションを作成します JUnitアノテーション（学習） 。これにより、両方のURLが同時にブラウザで開かれます。

availableFixes:
- name: "JUnitアノテーションについて学ぶ"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

IntelliJで Alt+Enter を押して有効化すると、コンテキストメニューが表示され、そこからドキュメントへジャンプできます。

複数のアクション

複数のアクションを設定すれば、各URLやチュートリアルを alt+enter のクイックフィックス・ポップアップメニュー内で個別の選択肢として表示できます。

例えば、@Parameterizedアノテーションの場合、公式ドキュメントとオンラインのサンプルコード集の両方にリンクさせたいと考えるかもしれません。

• https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests
• https://github.com/eviltester/junitexamples/blob/master/src/test/java/parameterized/junit5/InitialExampleTest.java

その場合は、アノテーションを検索するレシピを作成するだけです：

search:
  annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.params.ParameterizedTest"

そして、有用だと判断したサイトへのリンクを追加します：

availableFixes:
- name: "JUnitアノテーション（学習）"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "JUnitテストとは？（学習）"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

これで、両方のリンクがポップアップダイアログに表示されるようになります。

どのようなメリットがあるのでしょうか？

私自身、ライブラリの使用や学習の際、特にチームを率いて新しいライブラリの導入を支援する際に、これが役立つと感じていました。

また、ライブラリを作成するチームにとっても、標準的なドキュメントレシピを作成することで、ユーザーがライブラリや新機能を導入する際のガイドとして活用できます。

コードの保守とドキュメントの保守を異なるチームが行っている場合には、特に有用です。

SenseiはIntelliJ内の「preferences > plugins」からインストールできます（「sensei secure code」で検索してください）。

このブログ記事で使用したすべてのコードは、Githubのjunitexamplesモジュールにあります：https://github.com/SecureCodeWarrior/sensei-blog-examples