7

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.

  • 1
    There is CWEB by Knuth himself. – ChrisS Jul 16 '13 at 8:52
  • @ChrisS, as I stated in my question, I don't think verbose programming is a solution. I want to make minimal changes to the current source code, only adding some comments. – jwg Jul 16 '13 at 8:57
  • 1
    I think this is a good idea. I would not roll my own solution though. Have you had a look at Doxygen? It claims to be able to generate LaTeX code from the documentation in the source files. – Alexander Jul 16 '13 at 9:08
  • @Alexander my understanding is that Doxygen is quite proscriptive in terms of what kind of documentation you can write - descriptions of variables, methods and their arguments, which are built into a document by Doxygen, rather than a free-form piece of LaTeX which could be included in your own document. I will look again though, maybe I'm mistaken. – jwg Jul 16 '13 at 9:19
  • 3
    it's surely easy to write a script that processes your program into a latex script simply prints all the code verbatim, but typesets the comments. there are immensely many literary programming packages (cf ctan.org/topic/litprog ), but if your requirements are simple enough, it's possibly easier to do it yourself, rather than learning a new system. (if you're familiar with something like python, perl, lua, or whatever, that is) – wasteofspace Jul 16 '13 at 10:30
3

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.