PDA

View Full Version : Docs for Ext.ux.*



SamuraiJack1
3 Jun 2008, 9:57 AM
Browsing the sources, I've noticed, that they are documented inline. I mean, before every method there is a documentation for it, written with some markup rules, like this:


/**
* Slides the element into view. An anchor point can be optionally passed to set the point of
* origin for the slide effect. This function automatically handles wrapping the element with
* a fixed-size container if needed. See the Fx class overview for valid anchor point options.
* Usage:
*<pre><code>
// default: slide the element in from the top
el.slideIn();

// custom: slide the element in from the right with a 2-second duration
el.slideIn('r', { duration: 2 });

// common config options shown with default values
el.slideIn('t', {
easing: 'easeOut',
duration: .5
});
</code></pre>
* @param {String} anchor (optional) One of the valid Fx anchor positions (defaults to top: 't')
* @param {Object} options (optional) Object literal with any of the Fx config options
* @return {Ext.Element} The Element
*/
slideIn : function(anchor, o){
var el = this.getFxEl(); So, it seems that documentation that all we reading at http://extjs.com/deploy/dev/docs/ is autogenerated from sources.

Think will be more than just great, if such documentation can be autogenerated for Ext.ux namespace plugins (of course for those, which are written with those markup rules).

Comments?

devnull
3 Jun 2008, 11:58 AM
Fortunately this style of documentation is actually standardized and is called "scriptDoc". You'll probably find that most third party extensions have scriptDoc embedded, since most IDE tools make it easy to add. There are of course tools for extracting this documentation into various formats as well.

SamuraiJack1
4 Jun 2008, 12:30 AM
Fortunately this style of documentation is actually standardized and is called "scriptDoc". You'll probably find that most third party extensions have scriptDoc embedded, since most IDE tools make it easy to add. There are of course tools for extracting this documentation into various formats as well.

Good news. Then we can create centralized documentation for Ext.ux.* namespace rather easily (if core team will publish theirs extracting tool).
I'm in for this project, anyone else?

vmorale4
12 Jun 2008, 10:47 AM
Take a look at this thread:

http://extjs.com/forum/showthread.php?t=23347

Frank
13 Jun 2008, 10:53 PM
I'm making "Yet another" js Doc parser, just PM me if i could help, and test my app. as well.

SamuraiJack1
16 Jun 2008, 7:49 AM
I've founded a project, which I had in mind, starting this thread. Its JSAN: http://openjsan.org/ - the javascript clone of CPAN.
Basically, its an online collection of js modules. But, the main aspect of collection is "publishing discipline" which guaranties certain quality level of any uploaded module. The term "publishing discipline" can include for example, that modules should have inline js Doc documentation.

Currently JSAN is very "beta" and (comparing with shining Ext docs) not "presentable". It also missed the primary feature it should have - the browsing by namespace.

Anyway - think it can be used as a start point. Also think, that having the specification for docs ready (scriptdoc.org) and even the extraction tool ready (jsdoc.sourceforge.net) project is very realistic.

Well, what I'm talking about - I'm in for this project and if couple of volunteers will join, we can start it.

P.S. Am I right, that core team does not want to publish their own extraction tool? According to http://extjs.com/forum/showthread.php?t=1107 there were plans to do it.