65.9K
CodeProject 正在变化。 阅读更多。
Home

为 VS2008 和 VS2010 创作/集成 API 帮助

Derek Viljoen
starIconstarIconstarIconstarIcon
emptyStarIcon
starIcon

4.73/5 (11投票s)

2010 年 5 月 19 日

CPOL

4分钟阅读

viewsIcon

33831

为自己的 API 创建上下文帮助文件。

引言

不时地，我需要为组织内外其他开发人员使用的 API 进行开发。我一直希望能够将其打包成带有精美文档和专业外观的帮助文件。通过一些免费工具，生成专业外观的帮助文件相当容易，但我似乎总是在将其集成到 VS IDE 时遇到困难。在本文中，我将展示如何为 VS2008 和 VS2010 的新 Help3.x 格式解决这个问题。

您需要的工具

当然，您还需要 Visual Studio 2008/2010 中的一个或两个。

示例 API

public class API
{
	public API()
	{
	}

	public string Foo( string s )
	{
		return "Foo got " + s;
	}
}

GhostDoc

GhostDoc 项目是一个免费的 VS 插件，它极大地简化了在 API 源代码中生成 XMLDoc 注释的过程。当您定义和实现类时，只需在 VS 中键入三个“/”即可轻松创建这些注释，如下所示：

/// <summary>
/// 
/// </summary>
public class API
{
	/// <summary>
	/// 
	/// </summary>
	public API()
	{
	}

	/// <summary>
	/// 
	/// </summary>
	/// <param name="s"></param>
	/// <returns></returns>
	public string Foo( string s )
	{
		return "Foo got " + s;
	}
}

这非常有帮助，但是为了填写所有这些值，可能需要进行大量的手动编辑。然后，在注释块中记住类型引用的格式等问题也一直存在。

GhostDoc 通过在 VS 中提供“Document this”上下文菜单来提供帮助。

authoring1.png

结果是更加友好的

/// <summary>
/// Initializes a new instance of the <see cref="API"/> class.
/// </summary>
public API()
{
}

嵌入的 <see.../> 标签将在生成文档后生成指向文档其他部分的实时链接引用（而不仅仅是文本）。GhostDoc 的另一个优点是，如果存在基类或接口，它会智能地从中提取文档。

/// <summary>
/// Returns a <see cref="System.String"/> that represents this instance.
/// </summary>
/// <returns>
/// A <see cref="System.String"/> that represents this instance.
/// </returns>
public override string ToString()
{
	return base.ToString();
}

Sandcastle

Sandcastle 项目将帮助您获取这些文档注释并将其转换为 API 文档。首先，为了生成文档，您需要在项目“生成输出”选项中生成 XML 文档文件。

authoring2.png

这个生成的文件（以及实际的 DLL 文件）是 Sandcastle 完成其工作所需的输入。打开 Sandcastle Help File Builder GUI 并创建一个新项目。

authoring3.png

现在我们将从 Visual Studio 生成的 XML 文件添加到项目中。

authoring4.png

如下图所示：

authoring5.png

要为 VS2010 生成帮助文件，请选择 HelpFileFormat “MSHelpViewer”。

authoring6.png

这将导致 Sandcastle 生成一个文件（默认情况下为：Documentation.mshc）。

要为 VS2008 生成帮助文件，请选择“MSHelp2”。这将导致 Sandcastle 生成一系列文件（*.HxS、*.HxC 等）。

这些是我们现在需要集成到 IDE 中的原始帮助文件。

既然我们已经到了这一步，我想指出您也可以选择“HtmlHelp1”来生成经典的 *.chm（编译的 HTML）帮助文件。但是，这不能集成到任何 IDE 中，但它可用于与代码一起分发，例如在 MSI 中，或者通过“开始”菜单项访问。第四个选项是生成 HTML 文档。如果您想将文档托管在 Web 服务器上或将其压缩以与 API 一起分发，这是 Sandcastle 的另一个选项。

MSHC Migrate Utility

这是 Helpware 的一款商业工具，可让您从其他格式迁移到 VS2010 的新 Help3.x 格式。它不是免费的。我在此列出它，仅为完整性。

要将我们生成的 *.mshc 文件集成到 VS2010 中，我们只需要一个帮助清单文件（*.msha），如下图所示。

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>My API's Manifest</title>
</head>
<body class="vendor-book">
  <div class="details">
    <span class="vendor">Me</span>
    <span class="locale">en-us</span>
    <span class="product">My API</span>
    <span class="name">My API</span>
  </div>
  <div class="package-list">
    <div class="package">
      <span class="name">TestAPI</span>
      <a class="current-link" href="Documentation.mshc">Documentation.mshc</a>
    </div>
  </div>
</body>
</html>

这里重要的条目是确保 Package-list 部分指向您生成的文档文件（*.mshc），并且 <span ...>TestAPI</span> 值指向您 API 的最外层命名空间。将此文件保存在与 *.mshc 文件相同的目录中，并将其命名为“helpcontentsetup.msha”。

现在您已准备好将其与 VS2010 集成。您需要以管理员权限启动 VS2010（右键单击图标或菜单，然后选择“以管理员身份运行”）。您会知道您正在以管理员身份运行，因为 VS 的标题栏会显示“(Administrator)”。接下来，选择“帮助 -> 管理帮助设置”以启动帮助库管理器，如下图所示。

authoring7.png

选择“从磁盘安装内容”并浏览到您新创建的清单文件“helpcontentsetup.msha”，然后选择它。这将显示您的新 API 文档，选择“添加”，然后单击“更新”按钮将其集成到已安装的帮助文件中，如下图所示。

authoring8.png

瞧！您的 API 现在已注册到 VS2010 的本地帮助文件中。

authoring9.png

要与 VS2008 集成，我们需要创建一个 VS 扩展安装程序。向您的解决方案添加一个新项目（在“其他项目类型 -> 可扩展性”下）——一个新的帮助集成向导项目。这可以是设置项目或合并模块。在向导中，只需逐步完成选项，当您到达“源文件”时，添加我们用 Sandcastle 生成的 *.HxS 文件。

生成并安装生成的 MSI 将新的帮助文件添加到本地安装的帮助中。

请注意，在 VS2008 中，首次安装 MSI 后访问帮助系统时，它需要更新自身，这将需要几分钟时间（在我看来是相当长的时间……叹气）。

authoring10.png

有关所提及工具的更多文档，可在其各自的网站上找到。

历史

  • 2010 年 5 月 19 日：初始帖子
© . All rights reserved.