Using YUI Doc to Document JavaScript Files

To start, I need to say that the YUI Documentation tool is, by far, the most difficult to use tool developed by the YAHOO team. Getting YUIDoc working will take some time and patience. For starters, Python must be installed with several addons. Then once Python is working, your JavaScript files need to be completely reorganized, as each module must be in a separate directory. And lastly, if you augment an object in a separate file, such as "yahoo-ext/dom.js" does to "YAHOO.util.Dom", there does not seem to be a good way to link the two files together. The documentation said to use the uses parameters, but if you do not re-define the Dom class, then the parser throws an error and if you do redefine the Dom class, then the uses parameter causes an infinite loop. In the end the best solution is to define the class twice (two dom classes will show up in the documentation, but they both point to the same page). Once I figured all this out I was finally able to produce a JAVADoc for the Core Library Files introduced last week.

I have also augmented the Build.xml to have a "build.javadoc" target. This target references the file python.sh, which is required for a windows machine running cygwin (or another bash shell). If you are running on a non-windows machine, you should replace "${basedir}/python.sh" with "${python_home}/yourPythonExecutable". The problem on a window machine is the "python.exe" is not executable when executing bash from Ant, so instead we must wrap it in a bash script which will make the actual exe call. The bash script simply iterates through all the command line arguments and passes them directly through to "python.exe", so the exact same command line arguments should be used.

The Ant target "build.javadoc" works nearly identically to the "example.sh" provided in the bin directory of YUIDoc: first defining the arguments at the top of "build.xml", then using those argument variables in the exec task. The only difference, is that in the "build.javadoc" all the JavaScript files are copied into "${build_docjs}/moduleName/fileName" and the parser_in property is a space separated list of those copy directories, instead of your original JavaScript directories. This is required because the YUIDoc messes up badly, if multiple modules are located in the same directory.

For convenience I have added a window module that contains some of the Native JavaScript object and their JAVADocs. When I have some more time, I will add the rest.