标签: documentation

是否有代码/注释比率,您认为是良好(坏)代码健康的标志？

您能举例说明被认为编码良好的开源项目及其各自的评论比例吗？

(我意识到每个项目的比例都不是"真实的",并且很可能是那些表现出理论黄金比例的糟糕项目.仍然......)

如何自动生成Rails REST控制器的API文档？

有没有任何例子我可以使用RDoc来做这个？

有没有办法在visual-c ++项目中获取文档(如javadoc)？

我正在使用visual studio 2010.

谢谢!

在MSDN文档中,我们看到:

安慰

线程安全

这种类型是线程安全的.

的TextWriter

线程安全

此类型的任何公共静态(在Visual Basic中为Shared)成员都是线程安全的.任何实例成员都不保证是线程安全的.

我已经为Console一个开发了一个类似的(静态)类,那么如何将它标记为线程安全呢？我正在提取XML文档,我知道我可以像MSDN Doc那样使用这个部分.

希望我足够清楚......

感谢帮助 !

我们有一个用(优秀的)Sphinx记录的多模块项目.我们的设置与邮件列表中描述的设置没有什么不同.总的来说这很棒!但是我们有一些关于这样做的问题:

1. 子模块目录将包括索引链接.充其量这些将链接到错误的指数.(在最坏的情况下,这似乎会引发Sphinx中的错误,但我正在使用devel版本,这是合理的).有没有办法只为最顶层的toctree生成索引链接？

2. 是否有保持Sphinx配置在多个项目之间同步的最佳实践？我可以想象在一起乱砍某些东西from common_config import *,但对其他方法感到好奇.

3. 虽然我们在这里,但邮件列表中提出的问题(替代symlinking子项目文档？)从未得到回答.这对我来说并不重要,但对其他读者来说可能很重要.

我正在使用Sphinx为我的项目生成文档.

在这个项目中,我描述了yaml文件中的可用命令列表,一旦加载,就会在表单中生成一个字典,{command-name : command-description}例如:

commands = {"copy"  : "Copy the highlighted text in the clipboard",
            "paste" : "Paste the clipboard text to cursor location",
            ...}

我想知道的是,如果sphinx中有一个方法在make html循环期间加载yaml文件,以某些reStructuredText格式(例如定义列表)翻译python字典并包含在我的html输出中.

我希望我的.rst文件看起来像:

Available commands
==================
The commands available in bla-bla-bla...

.. magic-directive-that-execute-python-code::
   :maybe python code or name of python file here:

并在内部转换为:

Available commands
==================
The commands available in bla-bla-bla...

copy
  Copy the highlighted text in the clipboard

paste …

在python中,我们在开头用下划线指定内部函数/私有方法.是否应该使用docstrings记录这些功能(是否需要？)？(我的意思是正式文档,而不是帮助代码阅读器理解代码的文档)这是什么常见的做法？

我有两种方法用于密切相关的S3泛型(在另一个包中定义),因此我想在同一个Rd文件中记录它们.但是,当我单独记录他们的参数时,我会收到R CMD check关于"文档对象中的重复\参数条目" 的警告

##' Create a ggplot of a Kaplan-Meier Survival curve(s)
##'
##' @param data  A \code{survfit} object returned from \code{\link{survfit}}
##' @param \dots Unused
##' @return A ggplot2 object
autoplot.survfit <- function(data, ...) {
    NULL
}

##' @rdname autoplot.survfit
##' @param data A \code{\link{survfit.fortify}} object returned from \code{\link{fortify.survfit}}
autoplot.survfit.fortify <- function(data, ...) {
    NULL
}

第一个参数必须是data因为这是泛型定义的.但是,对于不同的方法,它的文档是不同的,只是因为它必须是不同的类.我可以有两个单独的文档文件,但它们是紧密耦合的,所以我想将它们保持在一起.我可以data在第一次调用中列出所有可能的类,并且在后续调用中没有任何内容,但这意味着我用第一个函数记录第二个函数而不是将它们全部保存在一起,就像Roxygen一样.

是否有可能通过多种方法获得roxygen来创建合法(不重复参数)？如果没有,处理这种情况的最佳方法是什么？

我有一个带有一组降价页面的项目,这些页面与链接相互关联

[Go to this page](subdir/MyOtherPage.md)

这些页面都被doxygen选中并出现在输出中,但链接不会改变为指向新的html再现.

我可以将链接更改为指向html页面,但我的项目托管在github上,然后这些链接将被破坏,因为github支持自动在markdown页面之间进行链接.

我在doxygen文档中看不到任何关于支持除外部链接之外的链接的内容.有没有办法让doxygen从降价产生HTML链接？

对于基本的Ruby方法,我将以下列格式为参数提供YARD样式doc.

# @param query [String] The search string to query.
# @param options [Hash] Optional search preferences.
def search(query, options = {})
  # ...
end

使用Ruby 2.0,现在可以使用关键字参数.但是,我不确定如何在YARD文档方面采用这种方法.

def search(query, exact_match: false, results_per_page: 10)
  # ...
end

如何将我的文件exact_match,并results_per_page在第二个方案？我应该继续使用@param关键字,还是有更好的东西？