标签: sandcastle

您的.NET源代码文档中有多少是太多了？

一些背景:我继承了一个很大的代码库,我已经在SO上发布了一些其他问题.这个代码库的一个"特性"是God Class,一个包含大约3000行代码的单个静态类,包含几十个静态方法.这是一个从一切Utilities.CalculateFYBasedOnMonth()要Utilities.GetSharePointUserInfo()到Utilities.IsUserIE6().这些都是不需要重写的好代码,只需重构成一组适当的库.我已经计划好了.

由于这些方法正在进入一个新的业务层,我在这个项目中的角色是为其他开发人员准备系统以进行维护,我正在考虑可靠的代码文档.虽然这些方法都具有良好的内联注释,但它们并不都具有XML注释形式的良好(或任何)代码doco.使用GhostDoc和Sandcastle(或文档X)的组合,我可以创建一些非常好的HTML文档并将其发布到SharePoint,这将使开发人员更多地了解代码的作用,而无需浏览代码本身.

随着代码中文档量的增加,导航代码变得越困难.我开始怀疑XML注释是否会使代码更难以维护,比如说//comment每个方法更简单.

这些示例来自Document X示例:

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer …

我正在使用sandcastle帮助文件构建器从我的c#代码的xml注释中生成文档文件.你知道如何将代码示例包含在帮助文件中,如msdn样式吗？

记录依赖属性的最佳方法是什么？

我应该在字段上放置xml文档:

/// <summary>Documentation goes here</summary>
public static readonly DependencyProperty NameProperty = 
        DependencyProperty.Register(...)

或在酒店:

/// <summary>and/or here?</summary>
public string Name{ get{...} set{...} }

还是我真的需要记录(和维护)两者？

我希望能够使用Sandcastle从现有主题文件(.AML)生成帮助文档.我使用Sandcastle帮助文件生成器来协助文档的配置和生成.

我不想发布任何代码文档,但是,如果我没有指定文档源(例如,项目,解决方案,DLL,exe等),那么构建将失败.

如何配置Sandcastle帮助文件生成器,以便我可以在不暴露代码文档的情况下生成文档？

我正在使用Sandcastle帮助文件生成器将我的C#XML-DOC文件输出为网站格式.如何从命令行完成相同的操作,以便在构建实际项目时可以在Visual Studio中将其添加为构建事件？

最终目标是在构建Visual Studio项目时构建网站帮助文件内容.

我已经尝试过使用引导的GUI安装中包含的补丁的Sandcastle,但除非我做了一些非常错误的事情,否则它基本上不适合记录F#代码(即使它对C#非常有效).也许它适用于其他人,在这种情况下,我会非常感谢我可以从一个简短的完整例子开始.非常感谢.

我知道Sandcastle不会输出F#程序集中的所有内容,但是那里引用的项目还没有准备好进入黄金时段.

肯定有一些可靠的工作并且"足够好"的东西？非常感谢任何建议.

编辑:非常感谢所有回复的人.布赖恩的回答最接近我想要的,所以我会接受它.然而,结果是似乎没有一个既适合F#又能可靠运行的解决方案.我现在会坚持使用文字评论.

我希望FsHtmlDoc.exe在某些时候开始工作.虽然我不能排除它已经有效但我只是没有正确使用它,谷歌搜索它表明我不是唯一一个发现它还不完美的人.

我正在使用XML和Sandcastle帮助文件生成器记录C#代码以生成HtmlHelp1帮助文件.我已经SyntaxFilters在Sandcastle项目上设置了属性,CSharp因为我只想生成与C#相关的代码语法.

我正在使用,<see langword="[langword]" />如下所示:

<see langword="null" />
<see langword="true" />
<see langword="false" />

正如我将SyntaxFilters属性设置为CSharp我期望将上述标记转换为等效的C#关键字,如下所示:

null
true
false

而是将它们转换为Visual Basic的等效关键字,如下所示:

Nothing
True
False

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

我正在使用Sandcastle帮助文件生成器构建VS 2010 C#项目的文档.我已将.xml编译器生成的文档和项目的Visual Studio解决方案.sln文件添加到文档源.我还将项目的可执行文件添加.exe到了References.但是,它没有建设.我得到警告和错误:

SHFB:警告BE0006:无法找到"C:\ Users\user\Music\Documents\Visual Studio 2010\Projects\SFML_Platformer\SFML_Platformer.sln"的任何文档资源(配置:调试平台:AnyCPU)

SHFB:错误BE0042:您必须以程序集或Visual Studio解决方案/项目文件的形式指定至少一个文档源

有什么问题？

我正在尝试为HTML帮助1和MS帮助查看器构建可移植类库(.Net40,Silverlight 4,.Net for Windows Store,Windows Phone 7.5)的文档.我只有一个"文档来源".该项目设置为使用vs2010文档样式(vs2005样式也存在问题).每当我尝试构建文档项目时,无论是通过Sandcastle帮助文件生成器GUI还是Visual Studio 2010,我总会得到相同的错误:

SHFB: Error BE0019: Unable to transform template 'VS2010.config': Could not find a part of the path 'C:\Program Files (x86)\Reference Assemblies\Microsoft\FSharp\3.0\Runtime\.NETPortable'.
Could not find a part of the path 'C:\Program Files (x86)\Reference Assemblies\Microsoft\FSharp\3.0\Runtime\.NETPortable'.

经过更多调查后,它看起来应该是目录C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\Templates\VS2010.config.如何将SHFB重定向到该目录而不是它正在尝试的目录？

我该怎么做才能建立文档项目？

通过进一步的调查,我想我已经推断出这个问题是文档源是一个可移植的类库.这是SHFB中的一个错误,还是我可以自行解决的问题？

我目前正在使用Sandcastle,Doxygen和JavaDoc为我编写的代码生成文档.是否可以使用这些包记录XML模式？如果没有,是否有任何(最好是免费!)包可以做到这一点？我可以自己编写文档作为Doxygen或Sandcastle中的额外概念主题,但我宁愿为我做一个工具!

一个例子是(虽然我不是XML Schema的专家!):

/// <summary>Top Node</summary>
<xs:element name="TopNode">
    /// <summary>Child Node</summary>
    <xs:element name="ChildNode" type="xs:string"/>
</xs:element>