Parsing Javascript files with phpDocumentor

Question

I've been playing with phpDocumentor recently and found it quite suitable for my needs. I'm largely working with PHP/HTML/JS/CSS codebases and would like phpDocumentor to parse my Javascript (and perhaps CSS) in order to keep it all together.

I've managed to get phpdoc to parse javascript files contained throughout the codebase - however it rejects the page-level docblock - which results in it rejecting the various tags (see below). I've found that by adding in a PHP open tag (with a JavaScript comment before it) to the top of the JavaScript file, I can get it to parse it just like a PHP file.

// <?php
/**
 * phpdoc goes here
 * @package
 * @todo
 *   - Todo 1
 *   - Todo 2
 */
function javascript(goes, here) {
}

I can think of a problem occurring should the webserver be setup to server .js files through PHP. Are there any other problems anyone can think of? Is there a better way to accomplish this?

Thanks

Answer 1

I think it's a bit naive assumption to think there is no similar tool for JavaScript.

There is a tool called JSDoc which is basically the same as phpdoc, but for JavaScript.

Answer 2

As far as potential problems, one that comes to mind is that since you're "tricking" phpDocumentor into parsing the docblock and the JS code, you're implicitly counting on the PHP tokenizer (which is how phpDocumentor parses PHP code internally) to successfully read your JS code and treat it as PHP code. When this succeeds, I think you'll have good results... your simple function example should probably succeed. However, if your JS code will not parse successfully as PHP code, then I bet phpDocumentor won't see it as a documentable code element, and therefore it will not appear in your docs.