Code Documenter

[TheMayoras]

Justification Having spent the last few months doing just about only writing VBA, it has become painfully clear to me that the VBE's lack of HTML documentation generator (Javadoc, Scaladoc, etc). It's not a huge deal when you are doing everything solo, but it's a much bigger deal when someone else is trying to use your code. An HTML documentation generator would help tremendously. I assume if anyone could excel at this, it would be Rubberduck. I have tried some other documentation tools (like MZ-Tools) and they work, but they are nowhere near something like Javadoc. After searching all over the internet for a solution, it seems that the consensus is that there isn't really a great code documenter.

Description A new Rubberduck feature that parses class, module, procedure, property comments and generates HTML documentation for the project. I was thinking something like Javadoc with something along the lines of '@Documentation(" "Description"="the description of the procedure" "Return"="a description of the return value" '@Param("Param1")="description of Param1" <- This would also add in the Param type in the docs "UseCase"="exampleVal = 1234 doubleNumber(exampleVal) ' Returns double 1234" ") or '@ClassDocumentation(" "Description"="the description of the class" ")

Additional context I don't know what the internals of this project look like, so I don't know if this is a possibility. I thought I would post it anyway. I looked in the Issues already and didn't see anything about this. I apologize if it's a duplicate. Lastly, the annotations are just a first thought, I'm sure anything you awesome people come up with is better if this does ever get implemented.

[rubberduck203]

Some thoughts on implementation:

Sandcastle uses a two step process to generate documentation from XML comments. First it uses reflection to get the doc comments from the code to build an intermediary file, then it turns that intermediary file into the actual output documentation.

If we can use our parser to generate that intermediate XML document, Sandcastle could be used to generate the final documents. This would save the RD community the effort of generating and formatting the final output.

[rubberduck203]

Related feature request & discussion here.

818

[Vogel612]

Sidenote: As it stands multiline documentation will require adjustments to the parser. Either to support multiline annotations or to add support for documentation comments.

I think we might have it easier decoupling the documentation from the annotation system

[TheMayoras]

Whatever works! I do like the idea of being able to specify "documentation types". For example, a way to specify that a procedure raises an error or to specify that a procedure accepts variants for a certain reason.

With the lack of multi-line, I assume that would make something like sample code hard to implement.

[retailcoder]

Linking XDocGen (MIT) - would be nice if they supported our @Description annotation syntax... there's a collaboration opportunity here.