问题标签 [code-documentation]

我浏览了这个论坛，并用谷歌搜索了这个论坛，但我不确定处理 Javadoc 和同一类中一起出现的注释的最佳方法是什么。

从我从 Sun/Oracle 的文档中可以看出，他们似乎建议（尽管我真的找不到明确的声明）Javadoc 应该列在注释之上。

请参阅他们的示例How and When Deprecate API's。

这对于像@Deprecated 或@Override 这样简单的东西非常有用。但是如果你使用 JPA 和/或 Hibernate 呢？您的类和方法肯定会被大量注释（有时每个类或方法有两个或更多注释）。

我猜 Javadoc 仍然在注释之上？

另外我想知道如何最好地使用注释？我已经看到了一些示例，其中注释“堆叠”在类、成员、方法之上。我见过其他人在同一行列出注释（通常是这里的方法）。

哪个最好？哪个更具可读性？

您是否“记录”了您在 Javadoc 中注释某些内容的事实？

我正在寻找关于这方面的一套好的文档和/或您自己关于什么是最易读/可维护的经验。

我正在使用代码文档和实时模板，但我完全不明白。

我读过Dr.Bob 的关于生成文档的文章和关于实时模板的 wiki 文章，但我对类描述有一个问题。

通过类描述，当我将鼠标光标指向类声明时，我了解 IDE 行为。

例如，我有这样的类，它的描述是：

后来在代码中我有这样的声明：

当我将鼠标光标放在类类型上时，我有这样的描述：

如您所见，并非每个 html 标记都由 IDE 引擎呈现。我真的很想知道如何呈现其他标签，尤其是带有代码示例的标签。是否可以？

我正在使用 Delphi 2009 Proffesional。

我一直在寻找代码文档编辑器应用程序。我指的不仅仅是像 doxygen 这样的生成工具，而是一个允许我编辑文档并直接在代码中更改它的应用程序。

有没有人知道一个好的编辑器？

谢谢！

大家好：有没有办法使用插件来提高 trac wiki 质量，该插件处理过时页面或引用不再存在的代码的页面、未链接的页面或更新率低的页面等工件-速度 ？我认为可能有几种启发式方法可用于防止 wiki-rot ：

• 最近编辑的数量
• 最近观看次数
• 页面是否链接到源文件
• wiki 页面的最后更新是否是 < 或 > 它链接到的源文件
• 在过去的“n”天里，wiki 中的整个目录是否已被使用/编辑/忽略

等等等等等等

如果不出意外，从管理的角度来看，仅这些指标对于每个页面和每个目录都会很有用。

我很好奇我是否可以记录我的文档modelFactory()，以便在您在 Netbeans 中开发时可以通过 doc helper 工具提示访问它。我的模型通过 modelFactory() 所以我可以做.....

它会给我一个模型数组或一个对象，具体取决于是否有多个结果。它确实压缩了我的代码很多。问题是当其他开发人员开始使用它时，我想让它知道哪些功能可用于$item. 请记住，虽然这一次它是一个“项目”模型，但下一次它可能是一个用户、博客文章或我们需要的任何其他东西。

是否可以为 NetBeans 记录此功能？我知道如果我这样做$item = new Item();，它将能够识别可用的内容。

更新

我正在寻找的部分是如何告诉我的 IDE ModelFactory 的输出是一个 $item 模型，因此它知道在哪里查找方法文档。

我们将 ReSharper 6.0 与 StyleCop 一起用于 ReSharper。

尽管我们使用 StyleCop 规则，即成员必须具有文档标头，但我们不希望 ReSharper 的代码清理工具为我们生成文档标头，因为它们不可避免地是垃圾。糟糕的文档标题比没有更糟糕，因为它们更不可能被更新而不是首先添加。

我们尝试在 ReSharper => Options => Tools => StyleCop 中关闭“将文本插入文档和文件头”设置，但是当您重新启动 Visual Studio 时，它会自行重置。

有什么想法可以阻止代码清理为我们创建文档标题吗？

我正在为我编写的一个小型 ActionScript 3 库编写自己的文档。

我试图尽可能地接近 Adob​​e Livedocs 的布局和内容，同时稍微清理一下。

我想我已经涵盖了人们在阅读我的文档时想知道的所有内容，但是在开始添加我创建的所有类之前，我不想错过任何重要的内容等。

有什么你希望一些文件有的吗？大多数文档中是否有您认为不必要的内容？

这是我到目前为止所得到的：https ://projectavian.com/docs/zephyr/#/entity

我试图涵盖的一些事情是：

1. 轻松直接链接到文档部分。即/#/class.propertyOrMethod如上。
2. 页面顶部的简洁表格简要列出了类中存在的每个属性、方法、常量或任何其他相关的主要内容。
3. 与每个属性或方法相关的清晰分隔的信息块，可以通过步骤 1 中的 URL 直接导航到。单击页面顶部表格中的相关文本也将链接到此处。
4. 方法参数的布局整洁，每个参数都有简明的解释。

在 Visual Studio 中，如何将默认的 XML 摘要注释片段从三行更改为一行？

目前它在我输入时提供了这个片段///：

我想要这个较短的片段：

我的摘要通常很简短，多余的 2 行是不必要的。

是否有此配置设置或一些可自定义的代码/自定义插件来解决此问题。

我查看了 Headerdoc 和 Doxygen 来记录源代码，但它们似乎都需要开发人员首先完成大部分工作。在 Visual Studio 中，键入\\\会生成文档框架，包括方法预期的参数。还有Ghostdoc，它根据方法的名称和参数猜测方法的作用。Xcode有类似的东西吗？

我怎样才能正确使用 jsdoc 发表此评论。有任何想法吗？？？