标签: documentation

据我所知,在C#类型/方法的XML注释中,可以在标记中引用泛型类型,如下所示:

///<see cref="name.space.typename&lt;T&rt;(paramtype)">

但我认为,还有另一种语法,不那么笨拙？什么,摆脱那些HTML实体的''？我现在找不到它.有人可以帮忙吗？

从WSDL生成某种人类可读文档的方法是什么？在过去,我使用过WSDL查看器(由Tomi Vanek提供)(请参阅我关于将其集成到NAnt的博客文章),我对结果感到满意,但我对任何可能的替代方案感兴趣.

我也听说过x3sp,但我还没试过.

我正在尝试使用Sphinx为我的代码库自动生成基本文档.但是,我很难指示Sphinx递归扫描我的文件.

我有一个Python代码库,其文件夹结构如下:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2

我运行了sphinx-quickstart <workspace>,所以现在我的结构看起来像:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2
    index.rst
    _build
    _static
    _templates

我已经阅读了快速入门教程http://sphinx.pocoo.org/tutorial.html,虽然我仍在尝试理解文档,但它的措辞让我担心Sphinx会假设我要手动创建我的代码库中每个模块/类/函数的文档文件.

但是,我确实注意到了"automodule"语句,并且我在快速入门期间启用了autodoc,所以我希望大多数文档都可以自动生成.我修改了我的conf.py来将我的src文件夹添加到sys.path然后修改我的index.rst以使用自动模块.所以现在我的index.rst看起来像:

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. automodule:: alphabuyer
   :members:

我在子包中定义了几十个类和函数.然而,当我跑:

sphinx-build -b html . ./_build

它报道:

updating environment: 1 added, 0 changed, 0 removed

这似乎无法导入我的包内的任何东西.查看生成的index.html在"Contents:"旁边没有显示任何内容.索引页面仅显示"mypackage(模块)",但单击它显示它也没有内容.

如何指导Sphinx递归解析包并自动生成它遇到的每个类/方法/函数的文档,而不必自己手动列出每个类？

我们目前正在使用DoxyGen来记录用C/C++,PHP和Java编写的代码.要拥有一致的环境,最好将它用于C#文档.

但是我们想知道:

• 您是否看到使用DoxyGen之外的其他内容生成的文档布局或结构有任何优势？我们正在为具有C#和.NET平台经验的外部开发人员生成文档.也许他们习惯了某种文档格式？
• DoxyGen与Visual Studio的集成程度如何？是否有能够从IDE内部一键式生成文档的东西？
• 是否有一些其他文档系统与Visual Studio更集成？

我刚刚开始玩事件驱动的架构,来自一个非常标准的面向对象的思维模式.

我注意到的第一件事是,理解和跟踪程序的难度似乎随着程序的大小呈指数级增长.虽然小型宠物项目很容易遵循,但感觉就像代码会迅速转向意大利面.

我理解我是这种发展思维的新手,并不是所有我的面向对象的担忧都会延续下去.有没有关于编写可维护,可理解的事件驱动代码的资源？使用node.js或Twisted或Event Machine的人对此有何看法？

我正在寻找一种从我的Javascript项目自动生成文档的方法.谁知道我怎么能这样做？

据我所知,有一些工具,如JSDoc,但我想知道你的意见,你最好的选择和原因.

谢谢!

编辑:为了清楚,我需要像JavaDOC或PHPDocumentor,但要使用我的Javascript源代码.

是否有一个普遍接受的Objective-C文档生成器(类似于Ruby的RDoc)？我见过Doxygen和ObjcDoc,我想知道哪个是最广泛使用的.

有没有人知道使用.proto源文件生成Google Protobuf文档的好工具？

我正在寻找一种方法来以编程方式获取ASP.net中方法的Xml-comments的摘要部分.

我查看过以前的相关帖子,但他们没有提供在Web环境中这样做的方法.

我不能使用任何第三方应用程序,并且由于Web环境,Visual Studio插件也没有多大用处.

我找到的最接近工作解决方案的是JimBlackler项目,但它只适用于DLL.

当然,诸如"提供.CS文件,获取XML文档"之类的东西将是最佳的.

现在的情况

我有一个Web服务,并尝试为它动态生成文档.

阅读方法和属性很简单,但是获取每种方法的摘要会让我失望.

/// <summary>
/// This Is what I'm trying to read
/// </summary>
public class SomeClass()
{
    /// <summary>
    /// This Is what I'm trying to read
    /// </summary>
    public void SomeMethod()
    {
    }
}

简短版本:我可以使用Normal包装模拟文件吗？statsroxygen

长版本:我正在开发一个软件包,并试图通过在一个标题下收集一些具有公共输入/参数的函数来使文档更具可读性,这将是对该组的通用引用.每个功能仍应独立地供最终用户使用.

我把文档作为灵感Normal,给出了许多与正态分布相关的方法,例如stats::dnorm().

当我搜索时,?dnorm我发现帮助部分的名称Normal即使Normal看起来不是导出的函数或对象.

我试过的是将以下内容放入funs.R:

##' @rdname funs
##' @name funs
##' @aliases sum1
##' @aliases prod1
##' @title Two functions
##' @param x X
##' @param y Y
##' @return sum1 returns x+y
##' \cr
##' prod1 returns x*y
##' @examples
##' sum1(3,4)
##' prod1(3,4)
##' @export
sum1 <- function(x,y) x+y
##' @export
##' @rdname funs
prod1 <- function(x,y) x*y

然后我继续 …