added a comment - - edited
I've been looking at this just now, the following are my notes:
- The @abstract tag is only valid in PHP 4, PHP 5 has a keyword abstract. (pasted from the phpdoc manual) No need to specify that any more as we require php5 of course exception to that is if we have old code with abstract classes that are presumed abstract and not actually noted as abstract by the keyword.
- Several boolean and integer's around the place.
- moodleform class
- $customdata doesn't have to be an array it can be anything
- Please fix the alignment of multiline params in moodleform method
- save_files method needs @deprecated tag
- get_new_filename comma after $elname should be removed
- save_stored_file missing an @param
- MoodleQuickForm class
- MoodleQuickForm method $action is either a string of a moodle_url
- accept $renderer appears to be a HTML_QuickForm_Renderer object
- setType includes a limited set of examples for PARAM_WHATEVER uses. Not your doing just noting that is totally in the wrong place. If we do provide an example it should be a method example not a param example. Actually PARAM_ACTION is deprecated and a bad example anyway lol.. would you mind tiding that up somehow Raj?
- exportValues missing @return
- Several elements have a typo in the setHelpButton method: $help => $helpbuttonargs and also missin deprecated tags etc.
- Missing docblock for MoodleQuickForm_checkbox constructor
- checkbox also missing deprecated etc from setHelpButton
- Please tidy up alignment on MoodleQuickForm_date_selector line 44.. that is a whole new way of doing a docblock and we need to minimise the number of different ways we do things. (in a couple of other places as well wont be mentioned again)
- date_selector accept $renderer is a HTML_QuickForm_Renderer (same in other places won't be mentioned again)
- form_filemanaer_x missing phpdoc block for property and constructor
- MoodleQuickForm_htmleditor missing php doc blocks for properties and constructor
- selectwithlink::removeOptions incorrect @param
On an interesting note I noticed several docblocks like the following:
/** @var string String with the html for hidden params passed in as part of a moodle_url
* object for the action. Output in the form. */
Do you know whether that sort of docblock validates OK? (I've never seen it before these changes)
Actually you introduced a couple of different variants to this.
I think we need to really limit the number of different ways we create phpdoc blocks.
I think the following two should be acceptable and the rest be changed:
/** A single line comment **/
* A multiline or single comment
* should look like this
Again all about consistency and example. Perhaps I'm being to up tight about it but the more variations I see the less I like our documentation.