I recently waded back into simple web application development (more on how that feels later), and one of the many aspects of coding that I’ve been refreshing myself on is how to best document what I’ve written so my future self doesn’t get too confused over what I implemented or why I implemented it in the way I did. The application is deadly simple, so simple that I hesitate to call it an application. The web page contacts a PHP script via an Ajax call, and the PHP script does its thing, sending back a JSON-encoded object. The client subsequently uses the object to display a message of success or failure.
As I said, deadly simple.
Nevertheless, as simple as the application is, I’ve been researching how best to document PHP and JavaScript. For PHP, the definitive answer appears to be phpDocumentor 2. For JavaScript, there is JSDoc. Here are some additional links that I found useful:
phpDocumentor
- phpDocumentor Quickstart (phpDocumentor for newbies): Good guide for newbies (like me!). The source code for the sample2.php file is especially helpful for people who need examples (like me!).
- Introduction to PhpDoc: Another great tutorial.
- Documentation with phpDocumentor: A much lengthier, two-part tutorial.
JSDOC
- An introduction to JSDoc: A friendly, very basic to getting yourself up and running with JSDoc.
- Use JSDoc: Official site for documentation.
Note that I haven’t actually tried generating documentation with either toolset; that’s a completely different challenge. I’ve mostly been following the format so that my documentation can be printed/generated if somebody (aka me!) wishes. And what I’ve come to understand is that learning how to document a language feels almost as complicated as learning the language itself.