☰

将 LaTeX 文档作为注释包含在源代码中

tag-icon • tag-icon listings input sourcecode
将 LaTeX 文档作为注释包含在源代码中

我正在开发一个大型 C# 项目（数百个源文件）。我正在尝试添加有关各种用户输入和选项的文档。

为了便于维护，我理想情况下希望能够将文档作为注释写在源代码中。各种接口和输入格式很可能会发生变化，而没有及时更新的文档甚至比没有文档更没用。

我的想法是使用类似 Doxygen 的东西，在注释中为 LaTeX 文档提供一个特殊指示器，例如在文件 DateManager.cs 中：

// -- name: parseDates
// \subsection{The format of the date file}
// The date file consists of $4$ alphanumeric string\ldots
// -- end
public void ParseDates(string s)

在 LaTeX 文件中

\includedocs{DateManager.cs}{parseDates}

此命令将打开源文件，找到相关部分，删除，//然后执行类似于\input或的操作\include。

这有点类似于详细编程，只是我希望它对现有源代码库的影响更小，而不是从根本上改变源文件和构建过程。

有人知道是否有工具可以做这样的事情吗？如果没有，有人可以建议我如何自己动手吗？我已经看到可以在注释中指出源代码的哪些部分应该包含在内lstlistings，但这仍然不允许我在注释中编写 LaTeX。

答案1

C# 对结构化注释有很多支持（编译器上的 /doc 标志，或 Visual Studio 中的“xml 文档”复选框），因此如果你将注释标记为

/// <summary>
///  The format of the date file
/// The date file consists of $4$ alphanumeric string\ldots
///  </summary>
/// <param name="s">...</param>
public void ParseDates(string s)

<param>然后，如果描述与声明的参数不匹配或者存在没有描述的公共方法等，编译器将会发出警告。

C# 编译器将输出一个 XML 文件，内容如下

    <member name="M:YourNamespace.ParseDates(System.String)">
        <summary>...</summary>
        <param name = "s">...</param>
    </member>

优点在于这是由编译器编写的，因此如果您有未包含在最终项目等中的 C# 文件，则只有正确的内容才会被记录下来。

有一些工具可以处理这个问题（特别是 sandcastle），但主要针对 HTML。对于 LaTeX 排版，任何基本文本或 XML 处理流都应该能够提取您需要的文本，而且由于格式保证更加一致，因此它比直接从源文件解析注释要容易得多。

相关内容