Autogenerated API documentation

[Eli Cochran]

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 - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work

. . . . . . . . . . .  .  .   .    .      .         .              .                     .

Eli Cochran
user interaction developer
ETS, UC Berkeley