用Java记录第三方库的使用的标准/官方方式是什么？

Question

在使用第三方库的类之前编写javadoc注释时，记录第三方库名称，版本和网址的标准/官方方式是什么？ 应该在描述中还是在块标记中提及（使用@see或自定义标记）？

Answer 1

取决于您要完成的工作。

版本和下载链接应位于依赖项管理工具（例如maven）的配置文件中。 这样，文档永远不会过时，并且不会在碰巧使用该特定API的每个类中重复。

为了发现哪个类使用哪个API，import语句可以很好地工作（是的，可以使用合格的类名来绕过import语句，但是很少有人这样做，因为这使源代码很难阅读）。 或者，只需从类路径中删除库，然后查看发生编译错误的位置。

我建议不要在javadoc中进行记录，因为您的类的调用者应该与它的实现无关。 也就是说，我认为API曾经是调用者不应该知道的实现细节-调用者不应该知道的内容不应该与他必须知道的东西混合在一起。

Answer 2

应该在描述中还是在块标记中提及（使用@see或自定义标记）？

只需在描述中的某处提及（个人），最好在末尾提及。 不要为这样的东西定义自定义标签，这不值得麻烦。 重要的是（如有必要）信息在那里。 没有设定惯例。

我故意说“如果有必要”-大多数时候我会说根本不需要。 但是，如果使用的库不是Maven所不熟悉的，并且/或者倾向于在发行版本之间进行重大更改，那么值得至少在某个地方进行记录。