phpDocumentator

[Andiministrator]

Just a suggestion: From my point of view it would be a good idea to use phpDocumentator for a project like CMSms. So you can write the documentation direct in the source code to each function, class, ...

The advantage would be, that the documentation is up to date everytime and nobody needs to waste time to update an external documentation. Another big advantage I see is that IDE's could use that documentation, so it would be easier for module developers to use core methods ...

I saw that the documentation style of phpDocumentator was already used in some files but not in all ...

[Jeff]

With the release of 1.8 we updated the core docs for module developers.

It is available at http://www.cmsmadesimple.org/apidoc

[Andiministrator]

Ok, thank you!

Are there any coding guidelines for module developers available? I saw that the skeleton module uses the phpDocumentator coding style, but most of available module doesn't

[Peciura]

I believe if every developer would explain what function is for what parameters does it take and  what data is returned, that would be 95% info you ever need.

Have to read documetation again, but here is what i remember.
Documentator comments starts with '/**' and as normal comment.
First comes Short function description, up to 3 lines.
'@params' at  the begining of the line indicates info about variables ( type, name, what is it for)
'@return' at  the begining of the line indicates info returned value (type and some more info)

It is simple :

/**
* Simple way to get category list suitable for FE forms
*
* @params object $mod Manadatory. Module object
* @params integer $text_to_value If 1  returns array($text => $value), else array($value => $text)
*
* @return array array($name => $id) or array($id => name) depends on $text_to_value
*/
function products_GetCategoryList(&$mod, $text_to_value = 1){
$catarray = array();
$categories = $mod->GetCategories();

if (count($categories) > 0){
if ($text_to_value){
foreach ($categories as $category){
$catarray[$category->name] = $category->id;
}
}
else{
foreach ($categories as $category){
$catarray[$category->id] = $category->name;
}
}
}
return $catarray;
}

There  are tags like '@global',  '@package' ... you can find them all here http://manual.phpdoc.org/HTMLSmartyConv ... t.pkg.html

It would be great if all modules and the rest of code were documented like that, they could have their own apidoc. But that sound  Utopian.