标签: documentation

早上好,下午好,晚上好或晚上好(取决于你的时区).

这只是关于C#中XML注释的一般问题.我从来没有对评论我的程序做过很大的贡献,我一直都是一个冗长的变量/属性/方法名称,让代码说明一切.如果我编写的内容相当令人困惑,我会写评论,但在大多数情况下,我不会写很多评论.

我正在阅读有关.NET,Sandcastle和codeplex上的帮助文件构建器中的XML注释的文章,它让我想要记录我的代码并为那些必须深入研究我的人生成一些很好的,有用的文档.代码,当我不在这里.

我的问题是关于标准和惯例.是否有"好"XML评论指南？你应该评论每个变量和属性吗？每个方法？我只是在寻找有关如何编写好的注释的提示,这些注释将由sandcastle编译成良好的文档,以便其他程序员在最终不得不处理我的代码时不会诅咒我的名字.

提前感谢您的意见和建议,Scott Vercuski

安瓿项目在docstring中使用了一些标签,就像javadoc一样.

例如,来自pool.py第86行:

def start(self, ampChild=None):
    """
    Starts the ProcessPool with a given child protocol.

    @param ampChild: a L{ampoule.child.AMPChild} subclass.
    @type ampChild: L{ampoule.child.AMPChild} subclass
    """

什么是这些标签,哪个工具使用它.

我有点担心这可能是重复的,但我搜索了网站,我能找到的每个问题似乎都更侧重于功能规范而不是技术规范.

我在寻找如何传达信息如何事情应该做的,而不是什么应该做的事.我认为在最简单的层面上,我正在寻找最好的方法来帮助向初级编码员解释实现功能规范的正确方法.

关于文档的大多数答案似乎都假设,一旦给出详细的需求列表,开发人员就会知道实现它的最佳方式,而且我倾向于发现通常情况并非如此.到目前为止我发现的最好的资源似乎是史蒂夫麦康奈尔的10*软件开发,但我想知道是否有其他人有一些有用的答案.

我正在使用Doxygen进行C++项目.当我构建html文档时,我收到以下错误:

C:/ Amir/Programming/Eclipse C++/CacheOptimization/src/CacheLruNaiveAlgorithm.cpp:19:

警告:找不到唯一匹配的类成员

void CacheOpt::CacheLruNaiveAlgorithm::init(TierList &tierList, TierMap *tierMap)

可能是这个警告的来源是什么？通常会导致什么？

编辑:

我的Doxyfile

DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "Cache Optimization"
PROJECT_NUMBER         = 1.0
PROJECT_BRIEF          = "Technion & LSI - Industrial Project"
PROJECT_LOGO           = 
OUTPUT_DIRECTORY       = "C:/Amir/Programming/Eclipse C++/CacheOptimization/doc/"
CREATE_SUBDIRS         = NO
OUTPUT_LANGUAGE        = English
BRIEF_MEMBER_DESC      = YES
REPEAT_BRIEF           = YES
ABBREVIATE_BRIEF       = "The $name class" \
                         "The $name widget" \
                         "The $name file" \
                         is \
                         provides \
                         specifies \
                         contains \
                         represents \
                         a \
                         an \
                         the
ALWAYS_DETAILED_SEC    = …

我正在为.NET寻找一个好的HTML文档生成器.Sandcastle我的需求太复杂,太麻烦,NDoc已经死了多年.

我的一个要求是它还应该处理代码约定,它们作为编译器发出的XML文件中的额外元素公开.

我希望当我将鼠标悬停在一个方法上时,我能够看到我的文档,当我将鼠标放在Java的方法上时,该方法的功能我知道/***/是如何完成的但是:

1. 你如何解释Params代表什么？

2. 你如何创建一个新行,或者使一个单词变为粗体或斜体？

我正在写一个R包,我正在用roxygen2记录我的所有函数.但是,我不希望所有功能都出现在软件包的手册中.如何指定应在包装手册中显示哪些功能,或哪些不应该？

我知道用一个前导点命名一个函数,例如,.f <- function()而不是f <- function()一个解决方案.还有其他解决方案吗？

看来该godoc工具不支持Go模块。

一个简单godoc -goroot=.的文件服务于项目文件，但它不会生成软件包的文档。我从projects源目录对它进行了测试，该目录还存储了go.mod和go.sum模块文件。

如何为Go模块内部的所有软件包生成文档$GOPATH？

在Go 1.12的发行说明中，该godoc工具将不包含在以后的Go版本中，并且只能go get在Go 1.12之后使用。一个应该使用Go go doc命令。但是，go doc不会生成“很容易阅读”的HTML页面。从Go源代码生成输出HTML或Markdown的文档是否有替代方法？