Questions tagged «javadocs»

最近，我一直在努力重构当前正在处理的部分代码库-不仅可以自己更好地理解它，而且还可以使其他从事代码工作的人更容易理解。 我倾向于认为自记录代码很好。我只是认为它更干净，并且如果代码能说明一切，那 ... 很好。 另一方面，我们有诸如javadocs之类的文档。我也喜欢这个，但是这里的评论（当然还有一般的评论）也有过时的风险。但是，如果它们是最新的，那么理解复杂的算法就非常有用。 最佳做法是什么？您如何在自我说明代码和javadocs之间划清界限？

18 java  documentation  refactoring  javadocs 

是否有一个与“不赞成使用”相似但又不同的好术语，表示方法或API已存在于代码库中，但由于其实现不完整或可能会发生变化而不应使用？（是的，我知道，这些方法不应该公开，yada yada yada。我没有创造自己的情况，我只是想尽力而为。） 人们有什么建议？实验性的，不完整的，还有其他吗？ 如果我正在为该API构建仍在不断变化的javadoc文档，那么我应该使用@deprecated标记还是有更好的约定？对我而言，@ preprecated表示此API很旧，可以使用更新的首选机制。在我的情况下，别无选择，但是API中的某些方法尚未完成，因此不应使用。目前，我无法将其设为私有，但我想在文档中添加明确的警告。

12 documentation  terminology  api  documentation-generation  javadocs 

在JavaDoc中X509Certificate getSubjectDN()指出： Denigrated，由getSubjectX500Principal（）代替。 我习惯在for方法中看到已弃用，该方法不再使用，但不可贬低。我发现了一个有关此特殊情况的错误报告，该错误报告已通过注释关闭： 这不是错误。“不推荐使用”仅在严重情况下使用。 当我们使用不推荐使用的方法时，建议采取的一般措施是停止使用该方法。 那么，将方法标记为“已贬义”时，建议采取的措施是什么？

11 java  terminology  javadocs 

我正在开发一个小型库，该库提供基本的，众所周知的字符串指标的实现。主要是为了我自己的教育。因此，只要有空闲时间，开发就会发生。 因此，我已经完成了大多数流程的自动化工作，因此我可以不费吹灰之力就发布一个版本。但是，维护Java文档仍然是一个负担，因为它包含示例。 随着API的发展，我不得不一次又一次地手动检查每个示例。有一个更好的方法吗？ 我已经考虑过将文档和示例移到一个单独的项目中（例如Caliper Tutorial），以便可以将其与常规代码一起重构和编译。但是，这确实使文档脱离了它所涉及的类。 嗯是的。我也想吃蛋糕。：D * <h2>Tokenization</h2> * * Tokenization cuts up a string into tokens e.g. * <code>chilperic ii son of childeric ii</code> is tokenized into * <code>[chilperic, ii, son, of, * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing * the individual tokens e.g. * …

9 java  documentation  javadocs 

我想以DRY方式编写Javadoc。但是关于Javadoc的Oracle文档说在重载方法注释中再次写同样的东西。我不能避免重复吗？

9 documentation  comments  dry  javadocs