Documenting your Drupal code using PHPDoc is part of building any kind of Drupal site that involves writing code, whether you're writing a mega-module like views, or just writing a quick front-end theme. This quick reference guide will get you going, or act as a simple refresher if you haven't done it for a while.
Why document?
To put it really simply, your code is not finished unless it is documented. Documentation helps other people understand your code, it helps you understand your own code once you've come back to it after 6 months, and it even helps you write better code, making you think about what you're writing. PHPDoc comments, in particular, which live at the beginning of funcitons, can automate the process of building the API for your code (this is what api.drupal.org uses).
However, I'm going to make the assumption you already want to document your code, otherwise you wouldn't have read this far, right?
What do I document?
Everything. No, seriously. Every function, class and method. If there is a function in your code that has no PHPDoc comment at the top, you should go back and write documentation for it.
When should I document?
As you're writing the code. If you write the code, and then go back to document it, the chances are you'll either give up because you can't be bothered, or your documentation will be worse because you won't remember as clearly what each individual function does. A good IDE (integrated development environment) will generate PHPDoc stubs, so you write the function signature (the line that starts "function" and has all the parameters) and the IDE will generate a blank PHPDoc block in the correct format. See our guide to setting up JetBrains PhpStorm if you want a recommendation on a solid IDE.
What if it's just a hook?
You don't need to fully explain what the hook does, but you still need to document it. Just write what hook you're implementing. The reader will then know to look in the API to find the definition for the hook. See Doxygen and comment formatting conventions for more.
- /**
- * Implements hook_menu().
- */
What if it's form API stuff?
You can just document it like this:
- /**
- * Submission handler for mymodule_form().
- */
- function mymodule_form_submit($form, &$form_state) {
- // code here
- }
- /**
- * Validation handler for mymodule_form().
- */
- function mymodule_form_validate($form, &$form_state) {
- // code here
- }
The function should be summarised on the first line
The first line of your PHPDoc block should contain a summary of the function's purpose.:
- /**
- * Retrieves a complete foo from the database.
- */
If you want to explain it in more detail, that's great. No, really, that's super that you want to write more than a single line! Do it! Leave a completely blank line between your summary and the rest of the PHPDoc block.
- /**
- * Retrieves a complete foo from the database.
- *
- * Will check to make sure that the foo's bar is correct before
- * attempting to do anything, and calculates the baz ratio
- * internally as it goes.
- */
Always document the return value
Some functions don't return anything. That's fine, just say it returns void. Otherwise, give the type that it returns, and give a description of what the caller can expect to get out of the function:
- /**
- * Retrieves a complete foo from the database.
- *
- * @return string
- * The text describing the foo.
- */
Note that the text describing what the function returns is indented by 2 spaces from the @return, and if it goes onto multiple lines, indent those too.
The comment block should never go beyond 80 characters in line length. All IDEs and most text editors can show you an 80-column "margin" or "print margin" which will let you know where to wrap comment lines.
Documenting parameters
You need to document every single parameter that gets passed into your function. You should use @param type $name (the type should come before the parameter name). Don't leave the type out! It helps massively in understanding what to give to the function.
- /**
- * Retrieves a complete foo from the database.
- *
- * @param int $foo_id
- * The numeric ID of the foo to be retrieved.
- *
- * @return string
- * The text describing the foo.
- */
- function mymodule_retrieve_foo($foo_id) {
- // code here
- }
Note how, in the example above, there is a blank line between the parameter listing and the return value.
For parameters that can accept more than one type, you can always write:
- /**
- * Retrieves a complete foo from the database.
- *
- * @param int|string $foo
- * The numeric ID or the machine-readable name of the foo to be retrieved.
- *
- * @return string
- * The text describing the foo.
- */
- function mymodule_retrieve_foo($foo) {
- // code here
- }
There are times when the parameter might be able to take so many types that you might want to write:
- /**
- * Retrieves a complete foo from the database.
- *
- * @param mixed $foo
- * The numeric ID, machine-readable name, or array representation
- * of the foo to be retrieved.
- *
- * @return string
- * The text describing the foo.
- */
- function mymodule_retrieve_foo($foo_id) {
- // code here
- }
Documenting arrays as parameters or return values
If the parameter or return value is an array, it's not enough to just declare that it's an array, you need to explain what keys are expected in the array, and what values they can have. Don't worry if your PHPDoc blocks are long. You're using a proper IDE, not Dreamweaver or notepad, right? So you have a function list and you can quickly jump to the definition of any function within your code? Of course you can, so you needn't worry about scrolling through loads of PHPDoc.
- /**
- * Retrieves a complete foo from the database.
- *
- * @param int $foo_id
- * The numeric ID of the foo to be retrieved.
- *
- * @return array
- * An array representing the foo, with these keys:
- * - id: the numeric ID of the foo.
- * - name: the machine-readable name of the foo.
- * - created: a UNIX timestamp representing the foo's creation date and time.
- */
- function mymodule_retrieve_foo($foo_id) {
- // code here
- }
What your documentation should say
Don't explain how PHP or Drupal works. Expect that the reader already knows this information. Explain, in human terms, what the code does, and highlight any unexpected behaviour. The reader should be able to understand how to call the function, what it does, and what it will give back, without having to read the code. The code is there, of course, but the element of human error can be reduced by properly documenting things.
A (more or less) complete example
- /**
- * Retrieves a complete foo from the database.
- *
- * Will check to make sure that the foo's bar is correct before
- * attempting to do anything, and calculates the baz ratio
- * internally as it goes.
- *
- * @param int $foo_id
- * The numeric ID of the foo to be retrieved.
- * @param array $options
- * An array of extra information used to retrieve the foo, with keys like this:
- * - color: a string representing the hex colour code for the foo.
- * - bar: a string representing the type of bar to be returned with the foo.
- * - html: TRUE or FALSE. Determines whether to return the foo as HTML or not.
- *
- * @return string
- * The foo represented as a string, surrounded by HTML if that option was provided.
- */
- function mymodule_retrieve_foo($foo_id, $foo_type) {
- // code here
- }
Your comments
I intend this to serve as a handy reference guide for anyone who quickly needs to see examples that aren't covered by the coding standards document, so do let me know about any corrections, or any additions you might like to see.Comments
This looks great, well structured and written.
I'm currently using NetBeans and it has PHPDoc support.
Great pleasure to visit your blog. I love to read interesting post that has knowledge to impart! I've learn so much from this. Thank you for sharing.
really well explained. thanks for this. will help me with my first big drupal project.
