senseiとのドキュメントリンクの使用

新しい図書館を学習することの難しさの1つ、または我々のチームを通して合意された習慣を共有することは、例を文書化して、作成しています.
ごく少数のサンプルプロジェクトを作成することが多いですが、実際のコードで作業するときにはオープンしません.
私はよく私たちの例、またはオンラインの例にリンクし、必要に応じてより多くの説明のためのURLを後藤にできるようにする能力を持っていることが素晴らしいと思いました.
Javaでは、Javadocのコメントがありますsee 注釈

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

サードパーティライブラリのこのようなJavadocは大きな助けですQuick Documentation Intellijの機能は、より詳細な例にアクセスできます.

しかし、私たちは皆、コメントがコードとしてしばしば更新されないということを知っています、そして、ウェブ存在メンテナンスはしばしば図書館メンテナンスから切り離されて、時々異なるチームによって全く実行されます.

どのように

Senseiは、ウィキペディアやサードパーティのチュートリアルサイトで長い形式のドキュメントへのリンクを提供するために、ライブラリの注釈やメソッドに一致する機能を提供します.
例として、私は@Test JUnitからの注釈
Javadocは非常に詳細であり、Quick Documentation ビューには、注釈を使用する方法を説明します.
しかし、Webサイトの公式ドキュメントは、読みやすく、より多くの例があります.
チームがライブラリを学び始めるとき、推薦されたチュートリアルのセットを持って、非常に役に立つことができます.
先生はgoto URLを開くことができるアクションは、私たちが外部サイトやドキュメントの例にリンクできるように、我々はチームとして、役に立つと思います.

goto URLの実装

これを実装するには、@Test JUnitからの注釈

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

それから私はgoto 私が役に立つとわかるURLの各々のための行動.
例えば

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

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

以下の例は単一のアクションを作成しますJUnit Annotations (learn) これは同時にブラウザの両方の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)"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

両方のリンクがポップアップダイアログに表示されます.

誰が恩恵を受けるだろうか。

私は、特にライブラリを使用して、学習するとき、特にこれが役に立つとわかりました.
また、ライブラリ内のライブラリや新機能の採用を通じて、ガイドの人々を助けるための標準的なドキュメントのレシピを作成することによって、これはライブラリを作成するチームの恩恵を受ける可能性があります.
コードメンテナンスとドキュメントメンテナンスが異なるチームによって実行されるならば、これは特に役に立ちます.
Intellij内からsenseiをインストールできますpreferences > plugins (単に「Senseiセキュアコード」を検索).
このブログ記事のすべてのコードはjunitexamples モジュールgithub.com/SecureCodeWarrior/sensei-blog-examples