问题标签 [code-documentation]

我找不到如何用 C 写评论。我的意思是我知道//and /* */，我的意思是我在哪里可以找到好的做法？就像我有一个函数一样，我该如何编写@param variable is the value bla bla，就像它是用 Java 完成的一样？

这有什么标准吗？或者我可以像在 Java 中那样做吗？

Mozilla 在线文档很棒，但有时我没有互联网连接，o'reilly javascript 权威指南中的参考也很棒，但缺乏方便的搜索功能。

我只是想知道是否有像railsapi、yard或jQAPI这样的 javascript 的东西

我有以下公共界面

带有内部后端类

问题：

• 只BarImpl实现Bar接口。
• BarImplDoStuff可以在方法中抛出异常。

Bar.DoStuff在xml 文档中记录这些异常是否有意义？

提前致谢，

在尝试使用 PEAR install 安装 PHPDocumentor 没有成功后，我按照官方网站上的详细说明手动尝试了：http ://www.phpdoc.org/docs/latest/for-users/installation.html

我下载了文件并在 /usr/bin/ 上创建了一个别名，但是当我尝试通过终端 y 执行 phpdoc.php 时，它显示错误。

这是我尝试的：

这是错误：

我正在使用 Mac Os X，如您所见，我使用 MAMP 来运行 Apache。这里发生了什么？为什么它试图打开一个不存在的文件？（因为它确实不存在于 PHPDocumentor 文件夹中）

谢谢。

我的问题更面向 Python，但也可能与 JavaScript 或其他脚本语言有关。

我通常使用静态类型语言（Java、C++、ActionScript，...）进行开发。

我喜欢不时使用 Python，有时我也需要使用 JavaScript。这些是动态类型语言。这没什么错，但我通常很头疼要了解函数或方法中需要哪些参数。即使它是我自己的带有一些文档字符串的代码也会发生！也许是因为眼睛必须在函数定义之外的地方寻找其他地方。

当然，答案应该在文档中。但有时根本不清楚，或者由于使用了鸭子类型，文档本身可能很难编写（“第一个参数是一个函数，它必须有一个 quack() 方法和一个 feathers(arg) 方法，其中 arg是一个字符串" )。我非常想要的是语言本身内部的一种参数描述（即使它是可选的，就像在 ActionScript 中一样）。

明确描述函数/方法的参数的最佳实践是什么？

如果创建一个特殊的装饰器（如果使用 Python），其目的是在我们使用它时检查数据的类型（但因为它将在运行时而不是在编写时使用，那么重点是什么）呢？

你认为这不应该是一个问题吗？比当前的文档字符串做得更多会使开发人员感到困惑，或者我的思想过于面向静态类型？

我真的很想为视图创建一个评论，并简要说明其用途。不幸的是，无法在 oracle 中为视图创建评论。此功能仅适用于可用的表、列和物化视图。我想知道您如何描述您的数据库视图？

当我在某个 .net 关键字上按 F1 时，它会将我带到该关键字的帮助。我有一个 .net 库及其文档。我正在使用这个库。当我在这个库中的某些功能上按 F1 时，如何使用 F1 获得库帮助？

一般来说，我们如何将本地文档与 .net 文档合并？

I'm writing my own library for the project at work for a browser application and I am having the same old problem deciding how to comment the code.

I'm trying to follow the JsDoc syntax, but will probably continue the Google Closure Compiler way. I may end up using two @return and @returns tags in the documentation, just for portability sake (when I setup the auto-generation of the documentation).

Now, the question, how do you document the return of a custom anonymous object from a function? For example:

JsDoc has an example of how a @param can be documented to expect object with certain fields, but not the @returns tag. Similarly, the Google Closure Compiler documentation of a Record Type is vague and has no example to work it out.

我正在使用 XML 和Sandcastle Help File Builder记录 C# 代码以生成HtmlHelp1帮助文件。我已将SyntaxFiltersSandcastle 项目的属性设置为，CSharp因为我只想生成与 C# 相关的代码语法。

我正在使用<see langword="[langword]" />，例如以下内容：

由于我已将SyntaxFilters属性设置为，因此CSharp我期望将上述标签转换为等效的 C# 关键字，如下所示：

相反，它们被转换为 Visual Basic 的等效关键字，如下所示：

有没有办法将这些标签替换为适当的 C# 关键字而不是 Visual Basic 关键字，或者我根本不应该使用 see 标签？

我最近安装了带有 StyleCop 4.7.34.0（带有 R# 插件）的 R# 6.1（C# 版本，不是完整版）。在项目中添加新类时，会自动添加文件头信息。你如何禁用它？

我已经在 StyleCop 的 R# 选项（选项 > 工具 > StyleCop > 标题部分）中关闭了“将文本插入文档和文件标题”的复选框......但仍然没有运气。

我还关闭了需要标头文档的 StyleCop 规则 SA1633 到 SA1640。

我发现这个相关的帖子表明：

ReSharper -> 选项 -> 工具部分 -> 代码清理 -> 选择 StyleCop 配置文件 -> 文档部分 -> 取消勾选 1600

但我的工具部分没有“代码清理”节点。不确定我使用 R# 的“C#”版本是否与此有关。