使用 Sensei 的文档链接

学习新库或在团队内分享最佳实践时，编写文档和创建示例往往是一大难题。

我们经常会创建一些小型示例项目，但在编写实际代码时却很少打开它们参考。

我常想，如果能直接链接到我们的示例或在线示例，并在需要时跳转到 URL 查看详细说明，那该多好。

在 Java 中，我们可以使用 JavaDoc 注释中的 see 标签：

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

第三方库中的这类 JavaDoc 非常有用，因为我们可以利用 IntelliJ 的“快速文档”功能来获取更详细的示例。

但众所周知，注释的更新往往滞后于代码，且网页文档的维护通常与库本身的维护脱节，有时甚至由完全不同的团队负责。

Sensei 如何提供帮助

Sensei 能够匹配库中的注解和方法，并提供指向 Wiki 或第三方教程网站的详细文档链接。

以 JUnit 的 @Test 注解为例。

其 JavaDoc 非常详尽，通过“快速文档”视图即可了解如何使用该注解。

但官网上的正式文档通常更易于阅读，且包含更多示例。

当团队开始学习一个新库时，拥有一套推荐的教程会非常有帮助。

Sensei 提供了一个 goto 操作，我们可以利用它打开 URL，从而链接到团队认为有用的外部网站和文档示例。

实现跳转 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（只需搜索“sensei secure code”）。

本篇博文的所有代码均可在 Github 的 junitexamples 模块中找到：https://github.com/SecureCodeWarrior/sensei-blog-examples