Documentation [message #685727] |
Sat, 18 June 2011 11:42 |
Timothy Wall Messages: 21 Registered: July 2009 |
Junior Member |
|
|
I'm working on building an eclipse IDE around an existing language interpreter. While I would love to have a basic framework of documentation, I'm not expecting more than a functioning example in the DLTK ruby implementation (with occasional glances at the TCL or JS implementations, depending on what seems more current).
What would be generally useful is if any time you extract a class or method, or start to set up DLTK scaffolding, is to add some javadoc to provide some insight into what you're doing. One or two sentences, like:
/** This is an experimental refactoring to help parsing for any DLTK target. */
/** This is a ruby-specific module that *might* help other targets. */
/** Not sure what this function does in core, but we need a hook here in order to blah, blah blah */
/** This function is internal to core JDT and does blah, blah, blah, but we need to expose it. */
Rather than:
// wtf?
// need to do more later
/** This function parses the foo. */
void parseFoo()
Consider that you can greatly leverage your knowledge with just a tiny bit of extra effort in the code. You'll be amplifying that knowledge, even if incomplete, to anyone else working on DLTK projects. Every time I introduce a new method or class I associate JavaDoc with it, it's really not that hard. Presumably you have a good idea what the code does before you commit it to version control.
Given that the forum and mailing list have such low activity, I'm hoping to find some assistance *somewhere*.
|
|
|
Powered by
FUDForum. Page generated in 0.03844 seconds