r84741 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:< r84740‎ | r84741 | r84742 >
Date:11:21, 25 March 2011
Author:reedy
Status:ok (Comments)
Tags:
Comment:
Add/update/improve various bits of documentation
Modified paths:
  • /trunk/phase3/includes/GlobalFunctions.php (modified) (history)
  • /trunk/phase3/includes/job/UploadFromUrlJob.php (modified) (history)
  • /trunk/phase3/includes/search/SearchEngine.php (modified) (history)
  • /trunk/phase3/includes/upload/UploadStash.php (modified) (history)

Diff [purge]

Index: trunk/phase3/includes/upload/UploadStash.php
——@@ -16,8 +16,12 @@
1717 // Format of the key for files -- has to be suitable as a filename itself (e.g. ab12cd34ef.jpg)
1818 const KEY_FORMAT_REGEX = '/^[\w-]+\.\w+$/';
1919
20 - // repository that this uses to store temp files
21 - // public because we sometimes need to get a LocalFile within the same repo.
 20+ /**
 21+ * repository that this uses to store temp files
 22+ * public because we sometimes need to get a LocalFile within the same repo.
 23+ *
 24+ * @var LocalRepo
 25+ */
2226 public $repo;
2327
2428 // array of initialized objects obtained from session (lazily initialized upon getFile())
——@@ -235,7 +239,7 @@
236240 * Arguably UnregisteredLocalFile should be handling its own file repo but that class is a bit retarded currently
237241 *
238242 * @param $stash UploadStash: useful for obtaining config, stashing transformed files
239 - * @param $repo FileRepo: repository where we should find the path
 243+ * @param $repo FSRepo: repository where we should find the path
240244 * @param $path String: path to file
241245 * @param $key String: key to store the path and any stashed data under
242246 * @param $data String: any other data we want stored with this file
Index: trunk/phase3/includes/search/SearchEngine.php
——@@ -630,10 +630,24 @@
631631 * @ingroup Search
632632 */
633633 class SearchResult {
 634+
 635+ /**
 636+ * @var Revision
 637+ */
634638 var $mRevision = null;
635639 var $mImage = null;
636640
637641 /**
 642+ * @var Title
 643+ */
 644+ var $mTitle;
 645+
 646+ /**
 647+ * @var String
 648+ */
 649+ var $mText;
 650+
 651+ /**
638652 * Return a new SearchResult and initializes it with a title.
639653 *
640654 * @param $title Title
Index: trunk/phase3/includes/GlobalFunctions.php
——@@ -3369,7 +3369,7 @@
33703370
33713371 /**
33723372 * Get a cache object.
3373 - * @param $inputType Cache type, one the the CACHE_* constants.
 3373+ * @param integer $inputType Cache type, one the the CACHE_* constants.
33743374 *
33753375 * @return BagOStuff
33763376 */
Index: trunk/phase3/includes/job/UploadFromUrlJob.php
——@@ -18,7 +18,14 @@
1919 class UploadFromUrlJob extends Job {
2020 const SESSION_KEYNAME = 'wsUploadFromUrlJobData';
2121
 22+ /**
 23+ * @var UploadFromUrl
 24+ */
2225 public $upload;
 26+
 27+ /**
 28+ * @var User
 29+ */
2330 protected $user;
2431
2532 public function __construct( $title, $params, $id = 0 ) {

Follow-up revisions

RevisionCommit summaryAuthorDate
r90248Minor doc fix to r84741...reedy23:40, 16 June 2011

Comments

#Comment by Happy-melon (talk | contribs)   11:30, 25 March 2011 
- * @param $inputType Cache type, one the the CACHE_* constants.
+ * @param integer $inputType Cache type, one the the CACHE_* constants.

I believe it should be @param $inputType Integer...

#Comment by Reedy (talk | contribs)   11:31, 25 March 2011

Both are valid, but technically, it's supposed to be @param type $variable

#Comment by Happy-melon (talk | contribs)   11:34, 25 March 2011

Coding convention#Inline documentation says otherwise...

#Comment by IAlex (talk | contribs)   12:06, 25 March 2011

For the record, I get the following in doxygen's stderr when type is before parameter name (doxygen version 1.7.1): 

includes/parser/Parser.php:3408: warning: argument 'Title' of command @param is not found in the argument list of Parser::fetchFile($title,$time=false,$sha1=false)
includes/parser/Parser.php:3408: warning: argument 'string' of command @param is not found in the argument list of Parser::fetchFile($title,$time=false,$sha1=false)
includes/parser/Parser.php:3408: warning: argument 'string' of command @param is not found in the argument list of Parser::fetchFile($title,$time=false,$sha1=false)
includes/parser/Parser.php:3408: warning: The following parameters of Parser::fetchFile($title,$time=false,$sha1=false) are not documented:
  parameter 'title'
  parameter 'time'
  parameter 'sha1'
includes/parser/Parser.php:3420: warning: argument 'Title' of command @param is not found in the argument list of Parser::fetchFileAndTitle($title,$time=false,$sha1=false)
includes/parser/Parser.php:3420: warning: argument 'string' of command @param is not found in the argument list of Parser::fetchFileAndTitle($title,$time=false,$sha1=false)
includes/parser/Parser.php:3420: warning: argument 'string' of command @param is not found in the argument list of Parser::fetchFileAndTitle($title,$time=false,$sha1=false)
includes/parser/Parser.php:3420: warning: The following parameters of Parser::fetchFileAndTitle($title,$time=false,$sha1=false) are not documented:
  parameter 'title'
  parameter 'time'
  parameter 'sha1'
includes/parser/Parser.php:3324: warning: argument 'Title' of command @param is not found in the argument list of Parser::fetchTemplate($title)
includes/parser/Parser.php:3324: warning: The following parameters of Parser::fetchTemplate($title) are not documented:
  parameter 'title'
includes/parser/Parser.php:3306: warning: argument 'Title' of command @param is not found in the argument list of Parser::fetchTemplateAndTitle($title)
includes/parser/Parser.php:3306: warning: The following parameters of Parser::fetchTemplateAndTitle($title) are not documented:
  parameter 'title'
#Comment by Reedy (talk | contribs)   13:06, 25 March 2011

Is it just how our doxy file is setup? Or is that how doxygen always does it..?

http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/maintenance/Doxyfile?view=annotate

#Comment by Reedy (talk | contribs)   23:34, 16 June 2011

Why the fixme?

#Comment by Aaron Schulz (talk | contribs)   23:36, 16 June 2011

Coding convention#Inline documentation

Status & tagging log