使用文档链接Sensei

学习一个新的库，或者在我们的团队中分享商定的做法，其中一个困难是记录和创建例子。

很多时候，我们创建了小的示例项目，但在处理实际代码时，我们并没有打开它们。

我经常想，如果能有能力链接到我们的例子，或网上的例子，并能在需要时到一个网址上获得更多的解释，那就太好了。

在Java中，我们有JavaDoc注释，它可以有一个see注解。

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

第三方库中这样的JavaDoc是一个很大的帮助，因为我们可以使用IntelliJ中的快速文档功能来获得更详细的例子。

但是，我们都知道，评论不像代码那样经常被更新，而且网站的维护往往与库的维护脱节，有时完全由不同的团队来执行。

Sensei 如何提供帮助

Sensei 提供了在图书馆注释和方法上进行匹配的能力，以提供与维基或第三方教程网站上的长篇文档的链接。

作为一个例子，我使用JUnit的@Test注解。

JavaDoc非常详细，而快速文档视图解释了如何使用注释。

但网站上的官方文档通常更容易阅读，而且有更多的例子。

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

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

下面的例子将创建一个单一的Action JUnit Annotations（学习） ，它将在浏览器中同时打开两个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" https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations value:"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)"
行动：
- 转到：
type:"URL"
value:"https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

然后这两个链接将出现在弹出的对话框中。

谁会受益？

在使用和学习图书馆时，特别是在领导团队并帮助他们采用一个新的图书馆时，我会发现这很有用。

这也可以使创建库的团队受益，通过创建一套标准的文档配方来帮助指导人们采用库或库中的新功能。

如果代码维护和文档维护是由不同的团队来完成，这将是特别有用的。

你可以在IntelliJ内部使用`偏好>插件`来安装Sensei （只需搜索 "sensei 安全代码"）。

这篇博文的所有代码都在Github的junitexamples模块中，在 https://github.com/SecureCodeWarrior/sensei-blog-examples