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, [email protected] 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 <[email protected]>:
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 - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
