![将 LaTeX 文档作为注释包含在源代码中](https://linux22.com/image/272164/%E5%B0%86%20LaTeX%20%E6%96%87%E6%A1%A3%E4%BD%9C%E4%B8%BA%E6%B3%A8%E9%87%8A%E5%8C%85%E5%90%AB%E5%9C%A8%E6%BA%90%E4%BB%A3%E7%A0%81%E4%B8%AD.png)
我正在开发一个大型 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 处理流都应该能够提取您需要的文本,而且由于格式保证更加一致,因此它比直接从源文件解析注释要容易得多。