Block.module missing some @phpdocs
eojthebrave - August 20, 2009 - 17:45
| Project: | Drupal |
| Version: | 6.x-dev |
| Component: | documentation |
| Category: | bug report |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed |
| Issue tags: | Needs Documentation, Novice, Quick fix |
Description
block.module has a couple of functions that are missing @phpdocs
#1
#2
Don't trust the previous one. Had some leftovers from another patch. This is the one.
#3
Ignore previous one again. I should stop patching for today :(
#4
In documentation, we write ID instead of id. Quick reroll?
#5
#6
Function descriptions should be in 3rd person. E.g. "gets" vs. "get" and "saves" vs. "save".
Also, I would prefer to see a bit more description of the return values. block_box_get() should say something like
An associative array containing the box information from the database.
rather than
The box.
What is a box, anyway?
On the save function, is the return value always TRUE? That seems odd. Why would a function return TRUE in all cases?
#7
Changing component also. Normally, API doc issues are put into component "documentation. And it is a doc "bug" of normal priority if some functions are missing doc.
#8
Hmmm... It appears that block_box_get() and block_box_save() have changed names in Drupal 7 since this patch was submitted. They are now called block_custom_block_get() etc. And they are still missing doc. All of the other functions in the block module have doc (not necessarily great doc, but at least a doc block).
The corresponding D6 functions are also missing doc, so if this patch is accepted for D7, it should then be backported (with appropriate function names) to D6.
#9
#10
Committed to CVS HEAD. Thanks.
#11
Needs port to D6.
#12
Here's a Drupal 6 port of the patch. Same functions, different names, exact same functionality. Marking RTBC as it's the same patch approved for D7.
#13
Thanks, committed to Drupal 6.
#14
Automatically closed -- issue fixed for 2 weeks with no activity.