问题标签 [code-documentation]

在类中记录静态变量的首选方法是什么？

还有什么……？

我一直在使用 Xcode 5 使用支持的注释语法记录我的代码的能力（请参阅这个 SO 问题）。Xcode 6 通过 Objective-C 源代码支持它，不幸的是不支持 Swift 源代码。

我想在 .swift 源上执行内联文档。知道如何做或最佳实践吗？

提前致谢，

路易斯

我在维基百科页面（文档生成器的比较）中看到 pandoc 可以用作文档生成器（就像 doxygen 一样）。

但是我没有在 pandoc 的文档或它的站点中找到一种从源代码注释中提取文档的方法，就像其他文档生成器那样。

那么我该如何使用 pandoc 来做到这一点呢？有没有办法从代码注释中提取 pandoc 的标记语言并从中创建 PDF 或 HTML 文档？还是维基百科的比较列表有误？

最近想使用 中的OpenCV库，但是绑定Python的文档很不清楚，不足。我想问在哪里可以找到一些详细的绑定文档。以前我用过，文档非常有帮助，更多我有疑问的地方可以去它的源代码。但是我认为绑定的源代码并没有提供太多信息。例如，我花了很长时间才发现标志在模块中，但标志在模块中PythonOpenCVPythonOpenCVOpenCVC++PythonCV_8UC1cv2.CV_8UC1CV_CAP_PROP_FPScv2.cv.CV_CAP_PROP_FPS.

我正在寻找一种标准方法来告诉 C++ API 的用户构造函数（或方法）是否接受在堆栈上分配的对象作为有效参数。是否有一种模式（例如特殊的构造函数/方法签名）告诉这里没有堆栈对象/堆栈对象在这里没问题？如果在没有另外记录的情况下允许堆栈对象，则默认假设是否存在常识？

问题说明：当一个类Vector6D有构造函数Vector6D(const Vector3D& upper, const Vector3D& lower)时，至少有两种方法可以实现该类：

a) 在构造函数中复制两个向量的元素并忘记Vector3D实例。

b) 聚合中的Vector3D实例Vector6D并继续使用引用进行后续方法调用。

Vector3D对于 a)分配实例的位置无关紧要。对于 b) 如果Vector3D实例是在堆栈上分配的，则当堆栈帧消失时，实现将停止工作。

因此，如果不查看实现或文档，用户就无法决定要做什么。

编辑：上下文是一个嵌入式软件项目，我不允许使用 STL、异常、boost 等。

Doyxgen 可以阅读以下两种风格的评论吗？

Doxy Block 评论采用以下格式：

libstdc++ 中的格式如下：

我有一些 C 代码具有静态初始化程序，其值是从宏派生的。这些初始化程序本质上是我的代码的外部 API。我正在寻找一种为我的代码自动生成文档的方法，以便初始化值很容易看到。

例如，下面是一个非常简化的 C 程序 #include

鉴于该程序，我想获得自动生成的文档，其中说明

1. 变量 myVar 有两个元素
2. .f 字段消耗的字节数
3. myVar 中每个元素的 .fa 字段的值

我可以使用gcc -E直接从 GCC 获取一些信息，但它并不能完全将 .fa 的值或 sizeof() 解析为数字。关于如何获得我想要的东西的任何想法（最好不使用 Doxygen）？

在官方文档中，你经常会看到这样表示的类型：

!Array.<string>=（例如这里：https ://docs.angularjs.org/api/ng/function/angular.module ）

这是什么意思？（尤其是我的示例中的 ! 和 = 符号）？它在哪里解释？这是我到目前为止一直缺少的通用标准吗？

我等到 6.0.1 才切换到 Xcode 6。打开我的一个项目后，我注意到方法或变量文档的快速帮助视图不再起作用。

例如一个简单的：

对于 a @propertyjust 导致 Xcode 在尝试通过单击代码中某处的属性的使用而不是显示文档本身来查看文档时说“已声明”。

Cocoa 自己的类文档仍然显示正常，我可以告诉我的文档被解析为错误地命名 a@param仍会导致警告。

我正在查看 KDE 的一些 API 参考页面，并专门查看他们的技术案例文档，并且我浏览https://techbase.kde.org的子页面越多，我就越喜欢他们的可读性，精益，清洁等设计。

有谁知道 techbase.kde.org 使用了什么文档生成器（如果有的话）？