I have a great position on the SMF team. Not only do I write documentation but I also have an additional group/role as a developer. So, I get to commit code to SMF and help make sure people understand how to use it. Code documentation is a perfect opportunity for me to do both at the same time.

I must say that when [Unknown] first created Simple Machines Forum and when Jeff & Joseph were working on YaBB SE, the comments and ease of understanding the code attracted me to them. Coding is an art form which I am very particular about. Some people paint, I tweak code.

Since the beginning, we've had comments at the top of each file explaining the functions in that file and the file itself. That was great 10 years ago. Now, there is a standard for documentation and that isn't it. PHPDoc is the defacto standard for documenting PHP code. It has a very easy to use and understand syntax. IDEs such as Eclipse and Zend Studio read this syntax and create tool tips and documentation. There are programs which will parse an entire project and create standalone API documentation such as PHPDocumentor and Doxygen. Some projects make use of its more powerful features, but we don't plan to go down that road. For now, I am working on taking those comments from the top of the file and moving them to above the function/class and documenting arguments and return values.

Antechinus asked me for some examples... we replaced all !!! with @todo. Now I have nice blue icons in Zend Studio. Here is an example of a function with some simple PHPDoc tags. These tags help my IDE show me tooltips for what the function does, what it returns, and what the parameters are. If I wanted to move this function, I'd copy the entire function and the entire doc block above it. That is a lot easier than going up and down the editor window to check the documentation.
/**
* Get the last action the executor did on target
* @param int $id_executor
* @param int $id_target
* @return string
*/
function lastActionOn($id_executor, $id_target)
{
global $smcFunc;

// Find out if this user has done this recently...
$request = $smcFunc['db_query']('', '
SELECT action
FROM {db_prefix}log_karma
WHERE id_target = {int:id_target}
AND id_executor = {int:current_member}
LIMIT 1',
array(
'current_member' => $id_executor,
'id_target' => $id_target,
)
);
if ($smcFunc['db_num_rows']($request) > 0)
list ($action) = $smcFunc['db_fetch_row']($request);
$smcFunc['db_free_result']($request);

return $action;
}


Visit PHPDoc and Doxygen for more information about using PHPDoc in SMF or your code.
If you want to get involved developing for SMF, fix a bug or create a customization.

Great!!!

Noted.