SteveEisner
2 Feb 2007, 4:50 PM
I think YUI-EXT's doc system is pretty amazing. That said, the one big problem I've been having has been that when I go to call some common functions, the name of the argument isn't enough to explain what I should pass in.
There are three examples that I can think of:
1) An event name argument such as el.on(). It would be nice to know what the valid events are. Of course, a complex object like BorderLayout does indicate the events, but not the simpler (non-YUIEXT) elements.
2) A config block argument such as new BorderLayout(). There are a lot of options available, but the documentation doesn't list any of them. As far as I know the only way to find these is to locate the correct blog entry?
3) For most function arguments, it doesn't tell you how it will call that function, ie. what arguments it will pass. A good example, though, is CompositeElements.each() which does show the arguments.
The functional reference may not be the best place for this information. Perhaps there should be an Events, Configuration Blocks, etc. section in the documentation. Along these lines, I think it would be helpful to have a one-pager startup doc that explains the most basic parts of YUI-EXT:
1) registering events
2) when common functions pass an Element and when it's a DOM obj
3) when you have to pass "true" to calls like getEls()
4) etc.
Sample code is great but doesn't always explain why you chose to write it the way it is...
Anyway, if I get a chance, I'll try to contribute a starter doc myself (but wouldn't expect it to be that great, given that I almost always get the basics wrong...)
Thanks again for an excellent library!
Steve
There are three examples that I can think of:
1) An event name argument such as el.on(). It would be nice to know what the valid events are. Of course, a complex object like BorderLayout does indicate the events, but not the simpler (non-YUIEXT) elements.
2) A config block argument such as new BorderLayout(). There are a lot of options available, but the documentation doesn't list any of them. As far as I know the only way to find these is to locate the correct blog entry?
3) For most function arguments, it doesn't tell you how it will call that function, ie. what arguments it will pass. A good example, though, is CompositeElements.each() which does show the arguments.
The functional reference may not be the best place for this information. Perhaps there should be an Events, Configuration Blocks, etc. section in the documentation. Along these lines, I think it would be helpful to have a one-pager startup doc that explains the most basic parts of YUI-EXT:
1) registering events
2) when common functions pass an Element and when it's a DOM obj
3) when you have to pass "true" to calls like getEls()
4) etc.
Sample code is great but doesn't always explain why you chose to write it the way it is...
Anyway, if I get a chance, I'll try to contribute a starter doc myself (but wouldn't expect it to be that great, given that I almost always get the basics wrong...)
Thanks again for an excellent library!
Steve