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

Question

在使用第三方库的类之前编写javadoc注释时，用于记录可以下载的第三方库名称，版本和Web地址的标准/官方方式是什么？是应该在说明中还是在块标签中提及（使用@see或自定义标签）？

Answer 1

取决于您想要完成的任务。

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

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

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

Answer 2

  

是否应在说明中或块标签中提及（使用@see或自定义标签）？

在说明书的某处，（个人）最好提到它。不要为这样的事情定义自定义标签，这不值得麻烦。重要的是（必要时）信息就在那里。这样做没有固定的惯例。

我说＆＃34;如果有必要＆＃34;故意 - 大部分时间我都说这根本不需要。但是，如果处理的是一个不广为人知的图书馆，而不是在Maven中和/或在发行版之间有变化的倾向，那么至少在某个地方可能值得记录这个。