I found a very nice post at David Mudrak's blog about many Moodle developement issues.
Here is an excerpt about javascript includes from the April 27, 2010 post that I found very helpful ...
Moodle core does a lot of work for you behind the scene with including YUI libraries and their dependencies in correct location of HTML produced by your code. The most straightforward way to include JavaScript on your page is to define the code in the file module.js in your plugin directory. To avoid collisions of global variables and functions, all your code is supposed to be wrapped in a namespace. Since 2.0, we put all Moodle JavaScript code into a global M object and plugins are expected to use their own M.plugintype_pluginname namespace. For example if you write an activity module called foobar, all your JavaScript functions should be defined in M.mod_foobar namespace.
To include your code at the page and to initialize it from PHP, use $PAGE->requires->js_init_call(), providing the name of the initial JavaScript function as the first parameter. This initialization function must accept YUI instance object as the first parameter which we call Y, as is common in YUI 3. Once you have YUI instance, you can do whatever magic this library offers to you, including the possibility to load additional YUI modules with Y.use(). The ‘Hello world’ example of using YUI in Moodle 2.0 could look like this:
Let us say you are working on FooBar activity module. In your PHP script, for example /mod/foobar/view.php, add a line
$PAGE->requires->js_init_call('M.mod_foobar.init');
Then create the file /mod/foobar/module.js with the following contents
/**
* @namespace
*/
M.mod_foobar = M.mod_foobar || {};
/**
* This function is initialized from PHP
*
* @param {Object} Y YUI instance
*/
M.mod_foobar.init = function(Y) {
alert('Hello world');
}
Or, instead of just displaying the alert, to modify the current HTML code (for example to add some elements via JavaScript or to remove some non-JS support code) just use
M.mod_foobar.init = function(Y) {
Y.one('#mycustomholder').set('innerHTML', 'Hello world');
}
See YUI 3 documentation for more great examples. You may also find this blog post useful