First,
<insert your favorite holiday greeting here>
Been slightly quiet here now because I’ve been feeling a bit lazy, but on this time of the year it’s allowed, right? ;)
I think I will start posting more regularily again after new years as I’m working on some interesting things.
Now with that out of the way, we can look at todays post!
If you use Aptana or Zend Studio for your codings, you’ve probably noticed they come with pretty good code-assist features which can tell you which methods etc. the classes have. But what if you define a variable and want to get assist for that? Or what if you make your very own class and want to enable descriptions and parameter lists etc. when you work with them?
Enter PHPDoc
Or JavaDoc, or JSDoc, or whatever else there are.
If you’ve browsed any Zend Framework source files or some others, you might’ve noticed the comment blocks in the style of…
/**
* This is a very helpful function indeed!
*
* @param bool $foo do we foo?
* @return bool true if we foo'd
*/ |
Those of you who have worked a bit more with PHP (or other languages) probably already know about these, which are kind of like small documentation languages. As you can see from the above, there are some tags such as @param and @return which have a specific meaning in the comment… There are others too but these are the basics.
Most newer IDE’s understand this kind of format for the language they are inteded for: Zend Studio understands PHPDoc, Aptana understands JSDoc, and so on, so these are the keys for getting assist.
Different cases
The most obvious case is when you’re making a class of your own. In that case, you just put docblocks before your methods and classes to give them documentation.
There’s one case which can be slightly hazy, though.
If you’ve used strongly typed languages, such as C#, you might know that Visual Studio can automatically give you assist on your variables based on their type. In loosely typed languages like PHP or JavaScript, this isn’t the case as the editor has no way to guess which kind of a variable are we talking about… or has it?
PHPDoc and JSDoc both have a tag called @type. This can be used to tell the IDE (and documentation, obviously) what type a variable is, such as like this with JSDoc:
/** * @type {Number} */ var myVar; |
In closing
If you weren’t already writing docblocks for your functions and classes, what are you waiting for? In addition to providing such helpful functionality like code assist, it’s always useful to document your code. Who knows if someone else has to look at your code in the future?