撰写伟大的Javadoc的技术提示 [英] Technical tips for writing great Javadoc

问题描述

您的 技术 提示是否写出了伟大的Javadoc？

What are your technical tips for writing great Javadoc?

我在寻找东西>超越标准解释功能内容的提示。大家都知道！ （对吗？）

I'm looking for things beyond the standard "Explain the function well" content-based tips. We all know that! (right?)

我对这些事情感兴趣：

• 什么标签应该是Javadoc的一部分，哪些不值得记住？


• 你什么时候使用 @see vs {@ link} ？


• 始终需要使用 @param 对于明显的参数？


• 如何阻止对方法的描述重新迭代 @param 和<$ c $


• 在Javadoc中包含HTML是否合适？

• What tags should definitely be a part of one's Javadoc, and which ones are not worth remembering?
• When do you use @see vs. {@link}?
• Is it always necessary to use @param for obvious parameters?
• How do you prevent the description of a method from re-iterating the @param and @return text?
• When is it appropriate to include HTML in Javadoc?

最后，任何人都可以指出一个好的简洁的Javadoc标签列表？

Finally, can anyone point to a good, succinct list of Javadoc tags?

推荐答案

• 我会说最重要的是 @author ， @deprecated ， @inheritDoc ， @param ， @return ， @引发。但是你应该看看所有的标签，以防万一。


• 当用作文本中的解释时，我们使用 @link 和 @see 作为参考列表。


• 是否有必要使用 @param 为明显的参数？否。


• 适当时使用 {@ inheritDoc}


• 以下是标签列表。


• I'd say the most important ones are @author, @deprecated, @inheritDoc, @param, @return, @throws. But you should have a look at all tags, just in case.
• We use @link when used as explanations inside the text, and @see as a list of references.
• "Is it necessary to use @param for obvious parameters?" No.
• Use {@inheritDoc} whenever appropriate.
• Here is a list of tags.

这篇关于撰写伟大的Javadoc的技术提示的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！