Sensei로 문서 링크 활용하기

새로운 라이브러리를 학습하거나 팀 내에서 합의된 관행을 공유할 때 겪는 어려움 중 하나는 문서화와 예제 생성입니다.

종종 작은 예제 프로젝트를 만들곤 하지만, 실제 코드를 작성할 때 이를 열어두고 참고하기는 어렵습니다.

예제나 온라인 가이드로 연결되는 링크를 제공하고, 필요할 때 URL을 통해 더 자세한 설명을 확인할 수 있다면 좋겠다고 자주 생각했습니다.

Java에는 see 어노테이션을 포함할 수 있는 JavaDoc 주석이 있습니다.

/**
 * @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 뷰를 통해 해당 어노테이션의 사용법을 설명해 줍니다.

하지만 공식 웹사이트의 문서는 읽기가 더 쉽고 예제도 더 풍부한 경우가 많습니다.

팀이 새로운 라이브러리를 학습하기 시작할 때, 추천 튜토리얼 모음을 갖추는 것은 매우 유용할 수 있습니다.

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

아래 예시는 하나의 액션을 생성하여 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"

그러면 두 링크 모두 팝업 대화 상자에 나타납니다.

누구에게 도움이 될까요?

저는 라이브러리를 배우고 사용할 때, 특히 팀을 이끌며 새로운 라이브러리 도입을 도울 때 이 기능이 유용했습니다.

라이브러리를 만드는 팀도 표준 문서 레시피 세트를 만들어 사용자가 라이브러리나 새로운 기능을 쉽게 도입하도록 안내할 수 있습니다.

코드 유지보수 팀과 문서 유지보수 팀이 다를 경우 특히 유용합니다.

IntelliJ의 `preferences > plugins`에서 "sensei secure code"를 검색하여 Sensei를 설치할 수 있습니다.

이 블로그 게시물에 사용된 모든 코드는 Github의 junitexamples 모듈에 있습니다: https://github.com/SecureCodeWarrior/sensei-blog-examples