ドキュメントリンクの使用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のQuick Documentation機能を使ってより詳細な例にアクセスすることができるので、とても助かります。

しかし、コメントはコードのように頻繁に更新されるものではありませんし、ウェブプレゼンスのメンテナンスは、ライブラリのメンテナンスとは切り離されていることが多く、場合によっては全く別のチームが行っていることもあります。

Sensei の支援方法

Sensei は、ライブラリの注釈やメソッドにマッチする機能を提供し、ウィキやサードパーティのチュートリアルサイトにある長文のドキュメントへのリンクを提供します。

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

JavaDocは非常に詳細で、Quick Documentationビューではアノテーションの使用方法を説明しています。

しかし、Webサイトに掲載されている公式ドキュメントの方が読みやすく、より多くの例が掲載されていることが多いです。

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

Sensei には、URLを開くために使用できるgotoアクションがあり、外部サイトへのリンクや、チームとして有用と思われるドキュメントの例を示すことができるようになっています。

Goto URLの実装

これを実装するには、Junitの@Testアノテーションにマッチする検索を作成します。

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

そして、便利だと思ったURLごとにゴートアクションを追加していく。

e.g.

• 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つのAction JUnit Annotations(learn )を作成し、2つのURLを同時にブラウザで開きます。

availableFixes:
- name: "Learn about JUnit Annotations"
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 Annotations (learn)"
actions:
- goto:
type:"URL"
value:"https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "What is a JUnit Test?(learn)"
アクション:
- 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