I've messed around with ScriptDoc a little bit, mostly because there
is some support for it in Aptana which is currently my IDE of choice.
I *like* ScriptDoc because it's very structured and I *don't like*
ScriptDoc because it is very structured. The structure is a bit
constricting but it is also very clear and consistent.
I also have had trouble remembering all the various keywords, etc. But
that's going to be true for any documentation scheme and the more I
use it, the easier it will become.
I like Natural Docs because they allow for more variation in both the
structure of the comments and keywords that are used. But is that a
good thing? Isn't it perhaps better to be using the same keywords and
structures across a project.
Another criticism that I have of the Natural Doc format (at least that
example) is the amount of white space that is used. I find it easy to
read but it will add to the scrolling that I need to do in the document.
Natural Doc:
/* Function: Multiply
Multiplies two integers.
Parameters:
x - The first integer.
y - The second integer.
Returns:
The two integers multiplied together.
See Also:
<Divide>
*/
Script Doc:
/**
* Multiplies two integers.
* @param {Integer} x The first integer.
* @param {Integer} y The second integer.
* @return {Integer} The two integers multiplied together.
* @see #Divide
*/
I toss this out, not a recommendation, just information.
Looking forward to seeing more examples.
- Eli
On Feb 20, 2009, at 2:33 PM, Colin Clark wrote:
Now that Infusion 0.8 has shipped, we've decided to move to auto-
generated API documentation produced from comments inline with the
code. There a lot of options out there, and I haven't had a chance
to take a thorough look at them.
Jacob Farber mentioned that Natural Docs is the tool that the
MooTools team uses for their documentation. After browsing their
site for a little while, I'm fairly impressed. Natural Docs'
philosophy is to keep the syntax as simple and readable as possible.
Here's what the documentation format looks like:
http://naturaldocs.org/documenting.html
Thoughts on this or other documentation formats for APIs?
Colin
---
Colin Clark
Technical Lead, Fluid Project
Adaptive Technology Resource Centre, University of Toronto
http://fluidproject.org
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
. . . . . . . . . . . . . . . . . .
.
Eli Cochran
user interaction developer
ETS, UC Berkeley
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
