[Tex/LaTex] Including LaTeX documentation as comments in source code

inputlistingssourcecode

I am working on a large C# project (hundreds of source files). I am trying to add documentation on various user inputs and options.

For maintainability I would ideally like to be able to write the documentation as comments in the source code. The various interfaces and input formats are quite likely to change, and docs which haven't been kept up to date will be even less useful than no docs.

My idea would be to have something Doxygen-like where there is a special indicator for LaTeX documentation within comments, eg in file 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)

and in the LaTeX file

\includedocs{DateManager.cs}{parseDates}

This command would open the source file, find the relevant part, strip away the // and then do something similar to \input or \include.

This is something akin to verbose programming, except that I want it to have a much more minimal impact on the existing source code base, rather than change the source files and the build process fundamentally.

Does anyone know if there exist tools to do something like this? If not, can someone suggest how I can roll my own? I have seen that it is possible to indicate in comments which parts of the source code should be included by lstlistings, but that still doesn't allow me to write LaTeX within comments.

Best Answer

C# has a lot of support for structured comments (the /doc flag on the compiler, or "xml documentation checkbox in visual studio) so if you marked up your comments as

/// <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)

Then the compiler will warn you if the <param> descriptions don't match the declared parameter or if there are public methods with no description etc.

The C# compiler will output an XML file with something like

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

The advantage being that this is written by the compiler so if you have C# files not included in the final project etc, just the right things get documented.

There are tools to process this (notably sandcastle) but mainly aimed at HTML. For LaTeX typesetting any basic text or XML processing stream should be able to extract the texts you need, and as the format is guaranteed to be more consistent it is a lot easier than parsing comments directly from the source files.

Related Question