Posted by JamesAn on April 2, 2009 at 8:11pm
I posted some questions on API formatting conventions in http://drupal.org/node/422084.
webchick recommended I post them here for consideration. The discrepancies I listed are all present in the core API document in the various api.php files.
Let me know what the convention is/should be. Thanks!
Comments
Response
1. Some core functions include @param and @return directives for functions with no parameters or return values
I'm against this.
2. Should @see (or any other) directive be used in the description?
I would prefer to see @see on it's own line, e.g
* Prepare a message based on parameters.* @see drupal_mail()
I think coder may already check the format of @see lines. I certainly added something on @see to coder.
3. Is there a strict order for @param, @return, @see, and @ingroup directives?
I would like to see the following:
* @see some_function1()
* @see some_function2()
* @ingroup some_group1
* @ingroup some_group2
* @param $variable
Some variable description that goes on and on
* @return $value
* Some return value description that goes on and on
4. Are paragraphs allowed to interject between groups of @param, @return, @see, and @ingroup directives?
I don't like paragraphs between @param and @return lines, and would like to see @param separated from @see/ingroup but have no opinion one way or the other about the others.
Commented on-issue, because
Commented on-issue, because some/most of the raised points are pointless to discuss.
True. But not so true for documentation of hooks. Providing info about whether a hook is supposed to @return something or not is valuable information.
@see has a clearly defined standard; as pointed out on-issue.
Defining a standard here makes not much sense. @param and @return are obvious, and @see can be used anywhere depending on context. @ingroup has no value on its own when reading the PHPDoc in PHP, because it is only used in the processed online API docs; all unimportant stuff should come last.
The only debatable thing I can see here is whether we want to standardize on blank lines between groups of directives. I would prefer that, because it helps in readability. And I also mean a blank line between @param and @return.
Daniel F. Kudwien
unleashed mind
Daniel F. Kudwien
netzstrategen
When I have used these in
When I have used these in core patches, I put the @see after the param and return values, and @ingroup last - essentially - as Sun suggests, in order of importance when you are reading the doc. I think having them above @param is not a good idea.