Automatic Documentation - Best method for creating a quick parser

Question

I have a large script that end-users need to edit so it requires somewhat redundant commenting. I use a layout for my files similar to this

//********************
//
// FileName
//    This script contains:
//    - Function X - does something
//    - Function Y - does something else
//
//********************

//********************
// Function X
// does something (<< I'd only like to enter this part once)
//********************
// Code here...

//********************
// Function Y
// does something else
//********************
// Code here...

I want to create a simple parser that does the copy/pasting of the function summaries to the file's header. I know of several tools that could help to accomplish this, like ANTLR and even RegEx, but what would be the best method?

Answer 1

Given the two options you mention, ANTLR and Regex, I would suggest ANTLR. ANTLR will be more flexible in the long run, and I believe you should be able to use it more effectively (it parses based in grammars). Regex approaches will be limited to regular languages, unless you add in some custom logic and whatnot.

As an example, I suspect you will have difficultly identifying comments inside blocks vs outside blocks with a regular expression. A CFG should be able to make such a distinction just fine. Then again, if you have control over the source you could just draft some specifications for what types of comments appear where...