问题标签 [code-documentation]

我正在研究以 JavaDocs 的方式记录我的代码的方法。

有任何想法吗？

我使用 UFT 11.52

到目前为止，我已经看过 NaturalDocs + Perl。

还有其他想法吗？

提前致谢。

我正在eclipse中用PyDev开发python。我正在寻找一个插件来帮助我在我的代码上执行文档。

有人知道这样的插件吗？

谢谢

我不知道在哪里寻求关于 Java API 文档和 Java 代码的澄清和确认，所以我在这里做。

在 API 文档中FileChannel，我发现要归档position并归档size在多个位置的错误。

这里只是一个例子。状态的 API 文档transferFrom(...)：

“如果给定位置大于文件的当前大小，则不传输任何字节。”

我确认 OpenJDK 代码也包含此代码...

...在FileChannelImpl.java与文档一致的文件中。

现在，虽然上面的代码片段和 API 文档看起来相互一致，但我“感觉”上面应该“大于或等于”而不仅仅是“大于”，因为position它是文件数据的基于 0 的索引，随意读取position == size()没有数据返回给调用者！（在position == size() - 1处，至少 1 个字节——文件的最后一个字节——可以返回给调用者。）

以下是同一 API 文档页面中的其他一些类似实例：

1. position(...): "将位置设置为大于文件当前大小的值是合法的，但不会改变文件的大小。" （应该是“大于或等于”。）

2. transferTo(...): "如果给定位置大于文件的当前大小，则不传输任何字节。" （应该是“大于或等于”。）

3. read(...)：“如果给定位置大于文件的当前大小，则不读取任何字节。” （应该是“大于或等于”。）

最后，返回值的文档部分read(...)甚至无法与文档的其余部分保持一致。这是它所说的：

read(...)

回报：

读取的字节数，可能为零，如果给定位置大于或等于文件的当前大小，则为 -1

所以，在这个单独的例子中，我确实看到他们提到了正确的事情。

总的来说，我不知道该怎么做。如果我今天编写与此文档匹配的代码，那么 Java 中的未来错误修复（代码或文档）将使我的代码出现错误，也需要我的修复。如果我今天自己按照今天的情况做正确的事情，那么我的代码一开始就会出错！

是否有正确的方法来记录另一个维度内的数组中的值/对象？

通常一个数组会这样处理：

但我需要这样的东西：

这显然不起作用，那么正确的 PHPDoc 表示法是什么？

所以我试图为我的 doxygen 为我的 Objective-C 项目生成的文档文档创建一个文档指南页面，但它似乎不起作用。

问题是@interface 导致 doxygen 尝试为页面创建一个接口，而不是仅仅为objective-c 输出markdown 语法高亮。有没有解决的办法？

感谢您的时间。

在我的编程课程介绍中，大部分内容都被分成带有注释的部分，如下所示：

我发现这是一种组织事物的有用方式，但很多时候，我需要在一段相当深奥的代码中间加上简短描述的开头或插入文档，然后我对我应该如何做感到困惑记录它：

也许这不是最好的例子，但我真正要问的是是否有更好的方法将代码拆分为公共部分？

问题：
应该为示例 SCParserDelegate 协议中的每个方法编写文档注释。

上下文：
我正在构建一个供第 3 方开发人员使用的解析框架。（这是我的第一个框架项目，所以我的开发过程是高度学术性的，以最大限度地学习。）

示例代码：

问题：
如何为上述示例代码中的每个方法和属性手动编写自己的文档注释块？

在 C# 中使用 XML 注释，我可以记录一个方法可能会引发异常：

但是，如果一个方法在其 XML 文档中没有exception标签，这可能意味着以下两种情况之一：

1. 作者彻底测试了该方法，确保它永远不会抛出异常，并希望通过不添加exception标签来记录这一事实。
2. 作者并不关心记录异常，所以这个方法可能会抛出任何东西。

根据我的经验，通常是第二种情况。那么问题来了：

如何明确记录方法永远不会引发异常？

到目前为止，我想出的最好的方法就是在方法中简单地提及它summary，例如“此方法不会引发异常”。但我想知道是否有更正式的方式来表达这一点，比如throw()在 C++ 中（尽管这可能是一个不好的例子）。

Julia 是否有任何内置工具用于从源代码生成文档？像doxygen这样的东西？

我找不到任何本机支持的东西，我很好奇是否确实存在某些东西，或者是否有人可以推荐外部应用程序。

Groovy JDK 文档，这里 http://groovy.codehaus.org/groovy-jdk/ 似乎没有显示对象的属性。我对这个网站很熟悉：http: //groovy.codehaus.org/，它有一些例子可以让人们了解属性，但至少看起来并不全面。

还有其他地方可以找到包含其属性的 JDK 扩展类吗？