cobra -doc could use some love

[Charles]

If you're looking for a juicer contrib project to sink your teeth into, the cobra doctool could use some attention. It basically works but is missing a slew of features and cross linking.

To get an idea of what we're trying to achieve here, see the Java 1.5 API docs. I don't think their choice or colors, borders, etc. is great, but the structure and cross linking is fairly nice.

The code that drives this is found in <workspace>/Source/DocGenerator.cobra. You'll find numerous TODO items in the doc string for the class as well as comments marked TODO in the code.

The compiler itself is a great test case for this:

Code: Select all

cd <workspace>\Source
cobra -doc -files:files-to-compile.text

Also, if you want to revamp the structure of the generated HTML, feel free.

You'll become more familiar with the compiler's AST nodes which define Cobra programs, if that interests you.

Anyone willing to pursue this?

[torial]

Can't say I'm willing to pursue it, but what about using SandCastle instead (both projects are under MS-PL)?

http://shfb.codeplex.com/
http://sandcastle.codeplex.com/

[Charles]

I never investigated other tools because I assumed they would not pick up contracts which are part of the public interface to a method. Likewise, I wanted an option to include unit tests since I perceive those as a form of documentation as well.

Maybe that's changing now that Microsoft has established a basis for contracts in .NET. Maybe if the unit tests were translated to MbUnit or NUnit those could be picked up as well.

Feel free to investigate further if this is important to you. I'm still on the hook for compiler bugs and (eventually) updating the site with news and a release. Divide and conquer...