PDA

View Full Version : Documentation Center .2 is up!



jack.slocum
18 Nov 2006, 11:57 AM
More updates to the documentation, many of the examples have been extracted from my blog, a new homepage and integrated YUI docs. What do you think? I think it's almost ready for a blog post!

http://www.yui-ext.com/docs/

tryanDLS
18 Nov 2006, 2:57 PM
I like it! Maybe change the link on the main page to point to this instead of the old YUI style stuff so they don't get confused and make comments about the old version.

arnair
18 Nov 2006, 3:01 PM
Looks incredible Jack - just when I thought the doc center couldn't get any better!

By all means blog it, but with something as sweet as this be prepared to get dugg/slashdotted :)

Arun

tryanDLS
18 Nov 2006, 3:06 PM
I saw your little box on one of the samples regarding viewing frame source. I never noticed this before , but if you have the 'WebDeveloper' extension installed for FF, you can also do a 'View Generated Source' and it will show you all the HTML that got dynamically build into the page. That could be really useful for debugging cause now you can save the entire HTML page and play with it w/out manipulating the DOM in the debugger, or wondering if you screwed up the way nodes were appended in the DOM

jbowman
18 Nov 2006, 6:17 PM
i like the loading indicator :D

Herm
18 Nov 2006, 7:58 PM
@Tim - ditto for the MS "internet explorer developer toolbar": right click > Full Source dumps the dom's html with full inline scripts. In FF 1.5 I used to use a 'view formatted source' extension which allows you to view the source inline and on the same page - sadly that ext has not been updated to FF 2 yet.

Peter

zquirm
19 Nov 2006, 1:39 AM
where is the documentation? The online documentation still is listed as Oct 5th.

where should I be looking?

jack.slocum
19 Nov 2006, 1:44 AM
http://www.yui-ext.com/docs/

I added a link above. :)

mdissel
19 Nov 2006, 12:09 PM
Nice set of documentation! Is there a simple way to copy it for offline use?

Thanks
Marco

jack.slocum
19 Nov 2006, 12:25 PM
It should be in the RC2 download.

tryanDLS
21 Nov 2006, 11:01 AM
Jack,

What do you think about adding an @default tag to the doc process to standardize how default property values are displayed?

jack.slocum
21 Nov 2006, 11:33 AM
I have thought about it. The problem is it would introduce a sub tag under parameters which currently isn't supported by the parser (and isn't supported by IDE's like Aptana that process comments).

One idea I did have though is something like this:

Now:

@param {String} name (optional) Description blob goes here (defaults to 'foo')

New way:

@param {String='foo'} name (optional) Description blob goes here

This might be ok because Aptana would just display String='foo' as the parameter type and most people could figure out what it means.

The other good thing about it is it is very short and easy to type so it might actually be used. :)

The big question is who wants to go update the thousands of lines of code to use the new syntax. :(

Animal
21 Nov 2006, 1:07 PM
Another important feature that no doc tools address, is config objects.

There are no @tags to document these. Currently, Jack adds a comment on the constructor illustrating the use of all possible config properties with the values explicitly set to the defaults.

How could this be addressed?

allaboutyui
21 Nov 2006, 6:23 PM
Nice examples Jack !

I'd like to suggest (and indeed I may write this myself) a brief 'putting it all together' grid example.

So that a user can see what code makes a Grid become an editable Grid, for example.

darkseed
22 Nov 2006, 1:16 AM
Is it me or is the documentation missing some subjects from the YAHOO.util tree ?
For example the 'Connection' class ?

Animal
22 Nov 2006, 1:26 AM
Also MixedCollection from ext.util

jack.slocum
22 Nov 2006, 3:06 AM
MixedCollection is still undocumented. Want to take a stab at it Animal? :D

I found the reason Connect is missing:

* @Class Connect

should be:

* @class Connect

I could make it case insensitive, but I don't think it should be.

The YUI code in general is documented very inconsistently.

Sometimes params are:

@param {String/HTMLElement}

others:

@param {String | HTMLElement}

others:

@param {String || HTMLElement}

and last:

@param {String or HTMLElement}

This is just one example. Sometimes they do:

/**
* My description of method foo ....
* @param {String} bar
*/

others,

/**
* @param {String} bar
* @description My description of method foo ....
*/

I guess everyone has their own preference, but I wish they would standardize it to make it easier on me. :D

I will upload a new copy of the docs soon.

brian.moeskau
22 Nov 2006, 3:14 AM
I would guess the issue is less about standardizing and more about Yahoo! having a team of many folks all throwing stuff in there. Maybe they should go with the Slocum model of development and get their team down to one person who just cranks stuff out left and right without sleeping ;)

Animal
22 Nov 2006, 3:32 AM
MixedCollection is still undocumented. Want to take a stab at it Animal? :D

It's not a huge class, sure I'll do it!

I'll grab the latest rev, and post the code back here in a few mins...

Animal
22 Nov 2006, 4:08 AM
Here's the latest code from SVN with doc comments added:



/**
* @class MixedCollection
* A Collection class that maintains both numeric indexes and keys and exposes events.
* @param {Boolean} allowFunctions True if the addAll function should add function references
* to the collection.
*/
YAHOO.ext.util.MixedCollection = function(allowFunctions){
this.items = [];
this.keys = [];
this.events = {
/**
* @event clear
* Fires when the collection is cleared.
*/
'clear' : new YAHOO.util.CustomEvent('clear'),
/**
* @event add
* Fires when an item is added to the collection.
* @param {Number} index The index at which the item was added.
* @param {Object} o The item added.
* @param {Object} key The key associated with the added item.
*/
'add' : new YAHOO.util.CustomEvent('add'),
/**
* @event replace
* Fires when an item is replaced in the collection.
* @param {Object} key he key associated with the new added.
* @param {Object} old The item being replaced.
* @param {Object} new The new item.
*/
'replace' : new YAHOO.util.CustomEvent('replace'),
/**
* @event remove
* Fires when an item is removed from the collection.
* @param {Object} o The item being removed.
* @param {Object} key (optional) The key associated with the removed item.
*/
'remove' : new YAHOO.util.CustomEvent('remove')
}
this.allowFunctions = allowFunctions === true;
};

YAHOO.extendX(YAHOO.ext.util.MixedCollection, YAHOO.ext.util.Observable, {
allowFunctions : false,

/**
* Adds an item to the collection.
* @param key {Object} The key to associate with the item
* @param o {Object} The item to add.
* @return o {Object} The item added.
*/
add : function(key, o){
if(arguments.length == 1){
o = arguments[0];
key = this.getKey(o);
}
this.items.push(o);
if(typeof key != 'undefined' && key != null){
this.items[key] = o;
this.keys.push(key);
}
this.fireEvent('add', this.items.length-1, o, key);
return o;
},

/**
* Returns the key associated with an item. NOT YET IMPLEMENTED.
* @param o {Object} The item for which to find the key.
* @return key {Object} The key for the passed item.
*/
getKey : function(o){
return null;
},

/**
* Replaces an item in the collection.
* @param key {Object} The key associated with the item to replace, or the item to replace.
* @param o {Object} (optional) If the first parameter passed was a key, the item to associate with that key.
* @return o {Object} The new item.
*/
replace : function(key, o){
if(arguments.length == 1){
o = arguments[0];
key = this.getKey(o);
}
if(typeof this.items[key] == 'undefined'){
return this.add(key, o);
}
var old = this.items[key];
if(typeof key == 'number'){ // array index key
this.items[key] = o;
}else{
var index = this.indexOfKey(key);
this.items[index] = o;
this.items[key] = o;
}
this.fireEvent('replace', key, old, o);
return o;
},

/**
* Adds all elements of an Array or an Object to the collection.
* @param objs {Object/Array} An Object containing properties which will be added to the collection, or
* an Array of values, each of which are added to the collection.
*/
addAll : function(objs){
if(arguments.length > 1 || objs instanceof Array){
var args = arguments.length > 1 ? arguments : objs;
for(var i = 0, len = args.length; i < len; i++){
this.add(args[i]);
}
}else{
for(var key in objs){
if(this.allowFunctions || typeof objs[key] != 'function'){
this.add(objs[key], key);
}
}
}
},

/**
* Executes the specified function once for every item in the collection, passing each
* item as the first and only parameter.
* @param fn {Function} The function to execute for each item.
* @param scope {Object} (optional=window) The scope in which to execute the function.
*/
each : function(fn, scope){
for(var i = 0, len = this.items.length; i < len; i++){
fn.call(scope || window, this.items[i]);
}
},

/**
* Executes the specified function once for every key in the collection, passing each
* key, and its associated item as the first two parameters.
* @param fn {Function} The function to execute for each item.
* @param scope {Object} (optional=window) The scope in which to execute the function.
*/
eachKey : function(fn, scope){
for(var i = 0, len = this.keys.length; i < len; i++){
fn.call(scope || window, this.keys[i], this.items[i]);
}
},

/**
* Returns the first item in the collection which elicits a true return value from the
* passed selection function.
* @param fn {Function} The selection function to execute for each item.
* @param scope {Object} (optional=window) The scope in which to execute the function.
* @return The first item in the collection which returned true from the selection function.
*/
find : function(fn, scope){
for(var i = 0, len = this.items.length; i < len; i++){
if(fn.call(scope || window, this.items[i])){
return this.items[i];
}
}
return null;
},

/**
* Inserts an item at the specified index in the collection.
* @param index {Number} The index to insert the item at.
* @param key {Object} The key to associate with the new item, or the item itself.
* @param o {Object} (optional) If the second parameter was a key, the new item.
* @return The item inserted.
*/
insert : function(index, key, o){
if(arguments.length == 2){
o = arguments[1];
key = this.getKey(o);
}
if(index >= this.items.length){
return this.add(o, key);
}
this.items.splice(index, 0, o);
if(typeof key != 'undefined' && key != null){
this.items[key] = o;
this.keys.splice(index, 0, key);
}
this.fireEvent('add', index, o, key);
return o;
},

/**
* Removed an item from the collection.
* @param o {Object} The item to remove.
* @return The item removed.
*/
remove : function(o){
var index = this.indexOf(o);
this.items.splice(index, 1);
if(typeof this.keys[index] != 'undefined'){
var key = this.keys[index];
this.keys.splice(index, 1);
delete this.items[key];
}
this.fireEvent('remove', o);
return o;
},

/**
* Remove an item from a specified index in the collection.
* @param index {Number} The index within the collection of the item to remove.
*/
removeAt : function(index){
this.items.splice(index, 1);
var key = this.keys[index];
if(typeof key != 'undefined'){
this.keys.splice(index, 1);
delete this.items[key];
}
this.fireEvent('remove', o, key);
},

/**
* Removed an item associated with the passed key fom the collection.
* @param key {Object} The key of the item to remove.
*/
removeKey : function(key){
var o = this.items[key];
var index = this.indexOf(o);
this.items.splice(index, 1);
this.keys.splice(index, 1);
delete this.items[key];
this.fireEvent('remove', o, key);
},

/**
* Returns the number of items in the collection.
* @return {Number} the number of items in the collection.
*/
getCount : function(){
return this.items.length;
},

/**
* Returns index within the collection of the passed Object.
* @param o {Object} The item to find the index of.
* @return {Number} index of the item.
*/
indexOf : function(o){
if(!this.items.indexOf){
for(var i = 0, len = this.items.length; i < len; i++){
if(this.items[i] == o) return i;
}
return -1;
}else{
return this.items.indexOf(o);
}
},

/**
* Returns index within the collection of the passed key.
* @param key {Object} The key to find the index of.
* @return {Number} index of the key.
*/
indexOfKey : function(key){
if(!this.keys.indexOf){
for(var i = 0, len = this.keys.length; i < len; i++){
if(this.keys[i] == key) return i;
}
return -1;
}else{
return this.keys.indexOf(o);
}
},

/**
* Returns the item associated with the passed key.
* @param key {Object} The key to find the associated item for.
* @return {Object} The item associated with the passed key.
*/
item : function(key){
return this.items[key];
},

/**
* Returns true if the collection contains the passed Object as an item.
* @param o {Object} The Object to look for in the collection.
* @return {Boolean} True if the collection contains the Object as an item.
*/
contains : function(o){
return this.indexOf(o) != -1;
},

/**
* Returns true if the collection contains the passed Object as a key.
* @param key {Object} The key to look for in the collection.
* @return {Boolean} True if the collection contains the Object as a key.
*/
containsKey : function(key){
return typeof this.items[key] != 'undefined';
},

/**
* Removes all items from the collection.
*/
clear : function(o){
this.items = [];
this.keys = [];
this.fireEvent('clear');
},

/**
* Returns the first item in the collection.
* @return {Boolean} the first item in the collection..
*/
first : function(){
return this.items[0];
},

/**
* Returns the last item in the collection.
* @return {Boolean} the last item in the collection..
*/
last : function(){
return this.items[this.items.length];
}
});
YAHOO.ext.util.MixedCollection.prototype.get = YAHOO.ext.util.MixedCollection.prototype.item;

jack.slocum
22 Nov 2006, 7:57 AM
That's too funny. All the syntax used is valid, or so I think, but I would just hope for a single way.

Thank you very much Animal, I will pop that in now. :)

jack.slocum
22 Nov 2006, 8:03 AM
Animal,

getKey is for the user of MC. This way you can add objects and not have to specify keys everywhere.


var mc = new YAHOO.ext.util.MixedCollection();
mc.getKey = function(el){
return el.dom.id;
}

mc.add(someElement);
mc.insert(0, someElement);
etc

The idea is then you can add objects and not have to worry about manually getting the key before adding.

I am using this in the LayoutRegion class.

tryanDLS
22 Nov 2006, 8:04 AM
I think with some of the forum issues of the last couple days, some posts were never flagged as updated.
In this one

http://www.yui-ext.com/forum/viewtopic.php?t=891&highlight=mixedcollection

I mentioned I think there's still a bug in indexOfKey. I still see it in Animal's updated version.

jack.slocum
22 Nov 2006, 8:29 AM
The forum should be good now.

That bug is good and squashed now too. :D