Best way to document AJAX + PHP code?

Question

Hello,

I have always been for documenting code, but when it comes to AJAX + PHP, it's not always easy: the code is really spread out! Logic, data, presentation - you name it - are split and mixed between server-side and client-side code. Sometimes there's also database-side code (stored procedures, views, etc) doing part of the work.

This challenges me to come up with an efficient way to document such code. I usually provide a list of .js files inside .php file as well as list of .php files inside .js file. I also do in-line comments and function descriptions, where I list what function is used by what file and what output is expected. I do similar tasks for database procedures. Maybe there's a better method?

Any ideas or experiences?

Note: This question applies to any client+server-side applications, not just Javascript+PHP.

Answer 1

I think your method is pretty good. The only thing is that everything inside the js file is readable by others and therefore documenting what PHP files are used could lead to a security hole, in the off chance they can get to a file that returns something it shouldn't. Also, although not a big deal, on higher traffic sites, downloading say 500bytes of comments can add up.

Both of these are not big, but just thoughts I've had before.

Answer 2

I think it's best to take a hierarchical approach.

For api-level documentation like on the function and class level, write inline documentation in the code and generate html documentation out of them using the many documentation tools out there (JSDoc, phpDocumentor, OraDoclet, etc). Bonus points if your doc tools can integrate with your source control tools so you can jump to specific lines of code from your api docs.

Once you have your doc tools in place, start generating the documentation as part of your build process (you have a build process, right?) for each new build and push the documentation to a standard web location.

Once these api docs are online, you can create a wiki for high level documentation such as browser->web->db interactions, user stories, schema diagrams, etc. It's best to write in brief prose or bullet points for high level documentation, linking to api docs and source control when necessary.

Answer 3

Serve your javascript (and css) through PHP - you can keep your source files together for easy cross reference and with careful use of headers you can easily handle caching. Doing this also lets you have a nicely formatted comment-heavy source version which you can then condense or obfuscate before sending to the browser.

function OutputJs($Content) {
    ob_start();
    echo $Content;
    $expires = DAY_IN_S;
    header("Content-type: x-javascript");
    header('Content-Length: ' . ob_get_length());
    header('Cache-Control: max-age='.$expires.', must-revalidate');
    header('Pragma: public');
    header('Expires: '. gmdate('D, d M Y H:i:s', time()+$expires).'GMT');
    ob_end_flush(); 
}

Answer 4

For projects with a lot of javascript, I use a build system (makefiles) with a javascript minimizer. As the jsmin author notes, stripping comments "encourages a more expressive programming style because it eliminates the download cost of clean, literate self-documentation."

The bonus is that jsmin also strips comments from CSS - so you can start commenting freely there as well. (I find that using css classes is crucial for writing clear javascript.)

It's an interesting idea to use PHP to dynamically strip out the code and organize javascript files. Keep in mind that an important optimization for web apps is to reduce HTTP requests so it is often wise to join smaller javascript files together. (I've found that simply concatenating minimized js files into a single file, works great.)