Одна из трудностей, связанных с изучением новой библиотеки или обменом согласованными практиками между нашей командой, заключается в документировании и создании примеров.
Очень часто мы создаем небольшие примеры проектов, но мы не открываем их при работе с реальным кодом.
Я часто думал, что было бы здорово иметь возможность ссылаться на наши примеры или онлайн-примеры и иметь возможность перейти по URL-адресу для получения дополнительных пояснений, когда это необходимо.
С Java у нас есть комментарии JavaDoc, которые могут иметь см. аннотацию:
/** * @see Junit 5 Annotation docs */
JavaDoc, подобный этому, в сторонних библиотеках – отличная помощь, потому что мы можем использовать функциональность Quick Documentation в IntelliJ, чтобы иметь доступ к более подробным примерам.
Но мы все знаем, что комментарии обновляются не так часто, как код, а обслуживание веб-присутствия часто не связано с обслуживанием библиотеки и иногда выполняется совершенно другой командой.
Как Сэнсэй Помогает
Sensei предоставляет возможность сопоставления аннотаций и методов библиотеки для предоставления ссылок на длинную документацию на wiki или стороннем учебном сайте.
В качестве примера я использую аннотацию @Test из JUnit.
JavaDoc очень подробный, а в Quick Documentation view объясняется, как использовать аннотацию.
Но официальная документация на веб-сайте часто легче читается и содержит больше примеров.
Когда команда начинает изучать библиотеку, наличие набора рекомендуемых руководств может быть очень полезным.
У Sensei есть действие goto , которое может открывать URL-адрес, позволяя нам ссылаться на внешние сайты и примеры документации, которые мы, как команда, находим полезными.
Реализация URL-адреса Goto
Чтобы реализовать это, я бы создал поиск, соответствующий аннотации @Test из Junit.
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.api.Test"
А затем я бы добавил goto действия для каждого из URL-адресов, которые я нахожу полезными.
напр.
В приведенном ниже примере будет создано одно действие 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 я мог бы захотеть сослаться на официальную документацию и набор онлайн-примеров кода.
Я бы просто создал рецепт, который ищет аннотацию:
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"
Затем обе ссылки появятся во всплывающем диалоговом окне.
Кому это было бы выгодно?
Я бы счел это полезным при использовании и изучении библиотек, особенно когда руководил командами и помогал им внедрять новую библиотеку.
Это также может принести пользу командам, создающим библиотеки, путем создания стандартного набора рецептов документации, которые помогут людям освоить библиотеку или новые функции в библиотеке.
Это было бы особенно полезно, если обслуживание кода и обслуживание документации выполняются разными командами.
Вы можете установить Sensei из IntelliJ с помощью настройки > плагины (просто найдите “безопасный код сенсея”).
Весь код для этого поста в блоге находится на Github в модуле junit examples в github.com/SecureCodeWarrior/sensei-blog-examples
Оригинал: “https://dev.to/securecodewarrior/using-documentation-links-with-sensei-2jbc”