Sorry to hear that you find YUI3 so opaque. if you could perhaps indicate which bits you find confusing, we may be able to help further. It took me a little while to get my head around the way in which YUI3 handles things, but once it clicked it made a lot more sense for me and the benefits for Moodle become clearer.
I've been trying to improve the Moodle YUI documentation over the past year or so, but if there's something specific you think we're missing I can put pen to paper and try and clarify things further.
The way in which we now handle YUI (as of Moodle 2.5) is much more similar to the way in which YUI handle YUI and generally the upstream documentation is worth having on tap. The only real things to bear in mind as key differences are:
- you must write your JS in a YUI module (see the Shifter and Module docs below)
- our module namespace is moodle-frankenstyle_modname-yuimodulename
- you must include YUI modules from php using $PAGE->requires->yui_module('moodle-frankenstyle_modname-yuimodulename', 'M.frankenstyle_modname.yuiodulename.initFunction', array(array('a' => 'list', 'of' => 'arguments'));
This is the Moodle-specific documentation:
In terms of upstream documentation, the YUI API is really handy and I find myself delving into it to find and check things daily - http://yuilibrary.com/yui/docs/api/
The YUI user guides (http://yuilibrary.com/yui/docs/guides/) are also very useful, as are the examples which you'll find on the right-hand side in the user guides).
I'd also highly recommend Evan Goer's O'Reilly cookbook. He's provided a three-chapter sample at http://www.goer.org/YUI/ which is also extremely handy.
Hope that this helps, and as I say, if there's anything specific you think we could do with documentation on, I'll try my best to whip something up.
Best wishes and happy New Year,