Documentation: To auto-generate, or not to auto-generate?

[Justin]

What also might help with the increased amount of text, and loss of  
screen real-estate, due to comments, is to have the comments folded.

In Aptana you can set the comments to automatically be folded when you  
open a file. You do have to set this for each type of file (i.e. CSS,  
JS, HTML), but that is probably a good thing.

Here is an example of how to have comments automatically folded in  
your js files.

Open Aptana

Window > Preferences > Aptana > Editors > JavaScript > Folding

In this dialog make sure to check "Enable Folding" and whatever you  
want to initially fold. It supports (/*) and (/**) style comments.

Please note that this update will only take affect the next time you  
open a file. Meaning that if it is already open, the comments will  
still be expanded. I'm not sure if you exit Aptana and reopen it, if  
they will then be folded or not.

Just as a clarification, you will still be able to unfold whichever  
comments you want, by clicking on the + beside them.

- Justin

On 6-Mar-09, at 2:20 AM, antranig at caret.cam.ac.uk wrote:

> I feel that although auto-generated documentation can, as you say,
> never be an adequate replacement for a complete manually written
> component guide, it is no reason not to have some. Yes, the
> documentation of lots of frameworks that have only auto-generated
> stuff frequently looks extremely shoddy, but I think it does fill
> a need - especially for non-component oriented parts of the framework
> like Fluid.js, keyboard-a11y etc.
> Naturally for areas of the framework with more complex configuration,
> such as Reorderer, Pager and Renderer, this will have to be  
> supplemented
> with a good deal of detailed presentation and explanation of the
> meaning of their options and their interactions... I don't think
> anyone is suggesting that moving to autogenerated docs implies
> destroying pages like "List Reorderer API" and their kin? Those
> were an awful lot of work to produce that indeed it would be silly
> to stuff into a single .js file :P
>
> Boz, rather short of oxygen...
>
> Quoting Anastasia Cheetham <a.cheetham at utoronto.ca>:
>
>>
>> We recently decided that we would move to auto-generated API
>> documentation produced from comments inline with the code (see
>> discussion on the list titled "Autogenerated API documentation",
>> started February 20, 2009).
>>
>> I have been researching and playing with various tools for this,  
>> but I
>> had a bit of an epiphany this afternoon, and I think we need to re-
>> think this. I'd appreciate everyone's thoughts.
>>
>>
>> Our components are highly configurable - it is one of our primary
>> strengths. This configurability means that we provide implementors
>> with a variety of options for customizing a component. Explaining
>> these options in documentation takes words - often, quite a number of
>> them.
>>
>> As an example, have a look at the List Reorderer API page:
>>     http://wiki.fluidproject.org/display/fluid/List+Reorderer+API
>> This is a relatively straight-forward component, with a typical  
>> amount
>> of available customization.
>>
>> Here's the crux of the problem I'm seeing:
>> If we want to be able to automatically generate a page that includes
>> all of this information, then *all of this information will have to  
>> be
>> in the comments of the JavaScript file*. I think that having this  
>> much
>> text in the file will make it completely unreasonable to work with.
>>
>> Additionally: The List Reorderer is one of several flavours of the
>> Reorderer. Internally, all of the different flavours exist in a  
>> single
>> JavaScript file. I can't even begin to imagine how we could coax an
>> automated system into producing 5 different pages from a single file,
>> each with different but overlapping subsets of the information. We
>> would have to split the JavaScript itself up into multiple files, for
>> a start.
>>
>> And the Reorderer is not the only component that presents this issue.
>> The Inline Edit has a number of configuration; the Uploader has
>> several alternative subcomponents; the Pager has several alternative
>> subcomponents...
>>
>>
>> My fear is that any automatically generated documentation will lose
>> the cohesiveness that I think is a strength of what we've got now.
>>
>> Does anyone have any suggestions??
>
>
>
> ----------------------------------------------------------------
> This message was sent using IMP, the Internet Messaging Program.
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work