- The code needs to parse as PHP, so things like inline functions mess it up.
- The default phpDocumentor ini file doesn’t recognize files with
- The files need to have a <?php at the top.
Noting this, I wrote a small script that iterates through a directory of
.js files, parses them line by line, pulls out only the function
declarations (which, hopefully, don’t also have code on the same line)
and docblocks, and writes the output (with a <?php at the top) to a
same-named file in a different directory.
The script obviously requires phpdoc to be installed, and also requires
you to edit the phpDocumentor.ini file (installed with PEAR on my system
/usr/share/php5/PEAR/data/PhpDocumentor/phpDocumentor.ini) and add
a “js” line to the
[_phpDocumentor_phpfile_exts] section to get phpdoc
I was easily able to integrate this with a Makefile rule and create a single set of cross-linked phpdoc API docs including both JS and PHP files. I also added explicit package names (like “-PHP” and “-JS”) to keep things separated a little.
The script can be found at: https://github.com/jantman/misc-scripts/blob/master/js2phpdoc.php. It’s (obviously) free for any use, provided that you follow the license terms (leave copyrights intact, send modifications back to me, and update the changelog if you modify it).
My Makefile rule (which uses a temp directory to both keep the generated files separate from the source and keep the file paths as seen by phpdoc the same as the actual source):
.PHONY: docs docs: mkdir -p temp/js bin/js2phpdoc.php js/ temp/js/ cp -r inc temp/ cp *.php temp/ phpdoc -c docs/default.ini rm -Rf temp