在 Sandcastles 的单独文件中包含代码示例

Posted

技术标签:

【中文标题】在 Sandcastles 的单独文件中包含代码示例【英文标题】:Include code examples in separate file for Sandcastles 【发布时间】:2014-11-19 04:43:21 【问题描述】:

我正在尝试在使用 Sandcastles 生成的 CHM 文件中包含代码示例。这是我目前所拥有的:

/// <summary>
/// Lorem ipsum.
/// </summary>
/// <example>
/// <code>
/// public int Test
/// 
/// private int test  get; set 
/// private int test2  get; set; 
/// public int findE()
/// 
/// if(test == test2)
/// return Console.WriteLine("Variables are Equal")
/// 
/// else
/// return Console.WriteLine("Variables are not equal")
/// 
/// 
/// 
/// </code>
/// </example>

这非常混乱,我宁愿在我的 .cs 文件中没有这段代码。有没有办法将此示例代码放在单独的 .cs 文件中,并以某种方式在评论中引用它?所以相反我会有这样的东西:

/// <summary>
/// Lorem ipsum.
/// </summary>
/// <reference src="mycode.cs">
/// </example>

【问题讨论】:

【参考方案1】:

当然。假设您创建了一个外部代码文件 Example.cs。在那个文件中,你放置你的例子,被一个名为 region 包围。

#region example1
Console.WriteLine("Hello, World!");
#endregion

在您为其创建示例的元素的 XML 注释中,指定外部代码示例的来源:

/// <summary>blah blah my class</summary>
/// <example><code source="Example.cs" region="example1" lang="C#" 
/// title="Some Title to Display" /></example>
public class Hurr

 // ...

C# 不需要指定语言,因为这是默认设置,如果您不指定区域,它将包含示例文件中的所有代码。

另请注意,源文件路径是相对于您的 SHFB 项目文件的,不一定是 Visual Studio 项目文件。如果您配置代码块组件(在 SHFB -> 项目属性 -> 组件中),您可以指定不同的基本路径。

【讨论】:

以上是关于在 Sandcastles 的单独文件中包含代码示例的主要内容,如果未能解决你的问题,请参考以下文章

在 C++ 中包含来自单独文件夹的文件

从单独的文件中包含一个 Ruby 类

PHP 在函数中包含/要求

如何“运行”主包中包含多个文件的项目?

如何在单独的 js 文件中使用访问 django 模板变量,而不是在同一个 html 文件中包含小脚本块?

在 Flash 中包含所有类文件