From 9648f3b4d0f55e0767fd24f3ec2b2b03985d78c0 Mon Sep 17 00:00:00 2001 From: Nick Jenkins Date: Wed, 18 Apr 2007 09:50:10 +0000 Subject: [PATCH] Some small doc tweaks to reduce Doxygen warnings, namely: * @link. You might think @link would surely mean "here comes a web URL" ... but @link is a valid command in Doxygen, which means an entirely different kind of link (an internal link to somewhere, so that you can separate documentation and implementation). The result is a mess, and the best solution I can see is to use "@see" instead of "@link". * Warning: argument `nourl' of command @param is not found in the argument list of Linker::makeMediaLinkObj($title,$text='') * Moving few class descriptions to right above classes, and/or formatting into Javadoc style. * "@addtogroup Special Pages" --> "@addtogroup SpecialPage" so that all special pages have the same @addtogroup tag. * @fixme --> @todo (must have missed these before) * "@param $specialPage @see" remove the "@" in the "@see" to stop warning. * @throws wants type, then a brief description, to stop warning. This last one is for PHPdocumentor only, but it fixes something for PHPDocumentor, and should be neutral for Doxygen: * WARNING in includes/api/ApiFormatYaml_spyc.php on line 860: docblock template never terminated with /**#@-*/ --- includes/BagOStuff.php | 6 ++++-- includes/Categoryfinder.php | 22 +++++++++++----------- includes/DatabaseOracle.php | 2 +- includes/DatabasePostgres.php | 2 +- includes/Exif.php | 2 +- includes/Export.php | 2 +- includes/GlobalFunctions.php | 4 ++-- includes/IP.php | 2 +- includes/Image.php | 2 +- includes/Linker.php | 4 +--- includes/Sanitizer.php | 6 +++--- includes/SpecialAllpages.php | 2 +- includes/SpecialBooksources.php | 2 +- includes/SpecialConfirmemail.php | 2 +- includes/SpecialContributions.php | 2 +- includes/SpecialRandomredirect.php | 2 +- includes/SpecialRecentchanges.php | 2 +- includes/SpecialResetpass.php | 2 +- includes/SpecialUncategorizedimages.php | 2 +- includes/SpecialUndelete.php | 2 +- includes/SpecialUnusedtemplates.php | 6 ------ includes/SpecialUserlogin.php | 2 +- includes/SpecialUserrights.php | 2 +- includes/api/ApiFormatJson_json.php | 3 +-- includes/api/ApiFormatYaml_spyc.php | 8 ++++---- includes/api/ApiMain.php | 4 ++-- 26 files changed, 45 insertions(+), 52 deletions(-) diff --git a/includes/BagOStuff.php b/includes/BagOStuff.php index 7b7aaab45c..cc239369e2 100644 --- a/includes/BagOStuff.php +++ b/includes/BagOStuff.php @@ -28,8 +28,10 @@ * the PHP memcached client. * * backends for local hash array and SQL table included: - * $bag = new HashBagOStuff(); - * $bag = new MysqlBagOStuff($tablename); # connect to db first + * + * $bag = new HashBagOStuff(); + * $bag = new MysqlBagOStuff($tablename); # connect to db first + * * */ class BagOStuff { diff --git a/includes/Categoryfinder.php b/includes/Categoryfinder.php index 7a9d4277d0..7faae935e8 100644 --- a/includes/Categoryfinder.php +++ b/includes/Categoryfinder.php @@ -7,8 +7,8 @@ * articles are in one or all of a given subset of categories. * * Example use : - * - * # Determines wether the article with the page_id 12345 is in both + * + * # Determines whether the article with the page_id 12345 is in both * # "Category 1" and "Category 2" or their subcategories, respectively * * $cf = new Categoryfinder ; @@ -19,7 +19,7 @@ * ) ; * $a = $cf->run() ; * print implode ( "," , $a ) ; - * + * * */ class Categoryfinder { @@ -35,7 +35,7 @@ class Categoryfinder { /** * Constructor (currently empty). - */ + */ function __construct() { } @@ -62,8 +62,8 @@ class Categoryfinder { /** * Iterates through the parent tree starting with the seed values, * then checks the articles if they match the conditions - @return array of page_ids (those given to seed() that match the conditions) - */ + * @return array of page_ids (those given to seed() that match the conditions) + */ function run () { $this->dbr = wfGetDB( DB_SLAVE ); while ( count ( $this->next ) > 0 ) { @@ -84,10 +84,10 @@ class Categoryfinder { /** * This functions recurses through the parent representation, trying to match the conditions - @param $id The article/category to check - @param $conds The array of categories to match - @return bool Does this match the conditions? - */ + * @param $id The article/category to check + * @param $conds The array of categories to match + * @return bool Does this match the conditions? + */ function check ( $id , &$conds ) { # Shortcut (runtime paranoia): No contitions=all matched if ( count ( $conds ) == 0 ) return true ; @@ -131,7 +131,7 @@ class Categoryfinder { /** * Scans a "parent layer" of the articles/categories in $this->next - */ + */ function scan_next_layer () { $fname = "Categoryfinder::scan_next_layer" ; diff --git a/includes/DatabaseOracle.php b/includes/DatabaseOracle.php index 1c8b9b8e47..14ea7c2690 100644 --- a/includes/DatabaseOracle.php +++ b/includes/DatabaseOracle.php @@ -666,7 +666,7 @@ echo "error!\n"; } public function setTimeout( $timeout ) { - /// @fixme no-op + // @todo no-op } function ping() { diff --git a/includes/DatabasePostgres.php b/includes/DatabasePostgres.php index 6af0c023e1..e58ff0dd11 100644 --- a/includes/DatabasePostgres.php +++ b/includes/DatabasePostgres.php @@ -1101,7 +1101,7 @@ END; } public function setTimeout( $timeout ) { - /// @fixme no-op + // @todo no-op } function ping() { diff --git a/includes/Exif.php b/includes/Exif.php index ab2e209beb..a3689088b2 100644 --- a/includes/Exif.php +++ b/includes/Exif.php @@ -21,7 +21,7 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * - * @link http://exif.org/Exif2-2.PDF The Exif 2.2 specification + * @see http://exif.org/Exif2-2.PDF The Exif 2.2 specification */ /** diff --git a/includes/Export.php b/includes/Export.php index f685a6a409..1582d0d33a 100644 --- a/includes/Export.php +++ b/includes/Export.php @@ -17,11 +17,11 @@ # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # http://www.gnu.org/copyleft/gpl.html + /** * * @addtogroup SpecialPage */ - class WikiExporter { var $list_authors = false ; # Return distinct author list (when not returning full history) var $author_list = "" ; diff --git a/includes/GlobalFunctions.php b/includes/GlobalFunctions.php index e93bfdb44a..291224b832 100644 --- a/includes/GlobalFunctions.php +++ b/includes/GlobalFunctions.php @@ -1167,7 +1167,7 @@ function wfHttpError( $code, $label, $desc ) { * Note that some PHP configuration options may add output buffer * layers which cannot be removed; these are left in place. * - * @parameter bool $resetGzipEncoding + * @param bool $resetGzipEncoding */ function wfResetOutputBuffers( $resetGzipEncoding=true ) { if( $resetGzipEncoding ) { @@ -1401,7 +1401,7 @@ define('TS_ISO_8601', 4); /** * An Exif timestamp (YYYY:MM:DD HH:MM:SS) * - * @link http://exif.org/Exif2-2.PDF The Exif 2.2 spec, see page 28 for the + * @see http://exif.org/Exif2-2.PDF The Exif 2.2 spec, see page 28 for the * DateTime tag and page 36 for the DateTimeOriginal and * DateTimeDigitized tags. */ diff --git a/includes/IP.php b/includes/IP.php index fff9616107..51d92accb3 100644 --- a/includes/IP.php +++ b/includes/IP.php @@ -280,7 +280,7 @@ class IP { * Split out an IP block as an array of 4 bytes and a mask, * return false if it can't be determined * - * @parameter $ip string A quad dotted/octet IP address + * @param $ip string A quad dotted/octet IP address * @return array */ public static function toArray( $ipblock ) { diff --git a/includes/Image.php b/includes/Image.php index 14dcf3ddf7..6a5e730e5c 100644 --- a/includes/Image.php +++ b/includes/Image.php @@ -2204,7 +2204,7 @@ class Image } $dbw->insert( $table, $fields, __METHOD__ ); - /// @fixme this delete is not totally safe, potentially + // @todo this delete is not totally safe, potentially $dbw->delete( 'filearchive', array( 'fa_id' => $row->fa_id ), __METHOD__ ); diff --git a/includes/Linker.php b/includes/Linker.php index 96c71743d6..b2167638a3 100644 --- a/includes/Linker.php +++ b/includes/Linker.php @@ -681,8 +681,6 @@ class Linker { * * @param $title Title object. * @param $text String: pre-sanitized HTML - * @param $nourl Boolean: Mask absolute URLs, so the parser doesn't - * linkify them (it is currently not context-aware) * @return string HTML * * @public @@ -872,7 +870,7 @@ class Linker { * Since you can't set a default parameter for a reference, I've turned it * temporarily to a value pass. Should be adjusted further. --brion * - * $param string $comment + * @param string $comment * @param mixed $title Title object (to generate link to the section in autocomment) or null * @param bool $local Whether section links should refer to local page */ diff --git a/includes/Sanitizer.php b/includes/Sanitizer.php index dc12ec7fec..96f89dce32 100644 --- a/includes/Sanitizer.php +++ b/includes/Sanitizer.php @@ -711,10 +711,10 @@ class Sanitizer { * Given a value escape it so that it can be used in an id attribute and * return it, this does not validate the value however (see first link) * - * @link http://www.w3.org/TR/html401/types.html#type-name Valid characters + * @see http://www.w3.org/TR/html401/types.html#type-name Valid characters * in the id and * name attributes - * @link http://www.w3.org/TR/html401/struct/links.html#h-12.2.3 Anchors with the id attribute + * @see http://www.w3.org/TR/html401/struct/links.html#h-12.2.3 Anchors with the id attribute * * @static * @@ -738,7 +738,7 @@ class Sanitizer { * * @todo For extra validity, input should be validated UTF-8. * - * @link http://www.w3.org/TR/CSS21/syndata.html Valid characters/format + * @see http://www.w3.org/TR/CSS21/syndata.html Valid characters/format * * @param string $class * @return string diff --git a/includes/SpecialAllpages.php b/includes/SpecialAllpages.php index 398a59681b..9b89145b8f 100644 --- a/includes/SpecialAllpages.php +++ b/includes/SpecialAllpages.php @@ -6,7 +6,7 @@ /** * Entry point : initialise variables and call subfunctions. * @param $par String: becomes "FOO" when called like Special:Allpages/FOO (default NULL) - * @param $specialPage @see SpecialPage object. + * @param $specialPage See the SpecialPage object. */ function wfSpecialAllpages( $par=NULL, $specialPage ) { global $wgRequest, $wgOut, $wgContLang; diff --git a/includes/SpecialBooksources.php b/includes/SpecialBooksources.php index 58f25b4460..d3136ea443 100644 --- a/includes/SpecialBooksources.php +++ b/includes/SpecialBooksources.php @@ -4,7 +4,7 @@ * Special page outputs information on sourcing a book with a particular ISBN * The parser creates links to this page when dealing with ISBNs in wikitext * - * @addtogroup Special pages + * @addtogroup SpecialPage * @author Rob Church * @todo Validate ISBNs using the standard check-digit method */ diff --git a/includes/SpecialConfirmemail.php b/includes/SpecialConfirmemail.php index d20d9c6b96..e1feb8a47e 100644 --- a/includes/SpecialConfirmemail.php +++ b/includes/SpecialConfirmemail.php @@ -4,7 +4,7 @@ * Special page allows users to request email confirmation message, and handles * processing of the confirmation code when the link in the email is followed * - * @addtogroup Special pages + * @addtogroup SpecialPage * @author Rob Church */ diff --git a/includes/SpecialContributions.php b/includes/SpecialContributions.php index 248e23aee8..a41607cb79 100644 --- a/includes/SpecialContributions.php +++ b/includes/SpecialContributions.php @@ -374,7 +374,7 @@ function wfSpecialContributions( $par = null ) { /** * Generates the subheading with links - * @param $nt @see Title object for the target + * @param $nt see the Title object for the target */ function contributionsSub( $nt ) { global $wgSysopUserBans, $wgUser; diff --git a/includes/SpecialRandomredirect.php b/includes/SpecialRandomredirect.php index 60e9d6531b..903702a2d4 100644 --- a/includes/SpecialRandomredirect.php +++ b/includes/SpecialRandomredirect.php @@ -3,7 +3,7 @@ /** * Special page to direct the user to a random redirect page (minus the second redirect) * - * @addtogroup Special pages + * @addtogroup SpecialPage * @author Rob Church * @license GNU General Public Licence 2.0 or later */ diff --git a/includes/SpecialRecentchanges.php b/includes/SpecialRecentchanges.php index de8579ae84..84444e62c6 100644 --- a/includes/SpecialRecentchanges.php +++ b/includes/SpecialRecentchanges.php @@ -469,7 +469,7 @@ function rcDayLimitLinks( $days, $limit, $page='Recentchanges', $more='', $doall /** * Makes change an option link which carries all the other options - * @param $title @see Title + * @param $title see Title * @param $override * @param $options */ diff --git a/includes/SpecialResetpass.php b/includes/SpecialResetpass.php index b83375fa21..e16a2fb6ba 100644 --- a/includes/SpecialResetpass.php +++ b/includes/SpecialResetpass.php @@ -134,7 +134,7 @@ class PasswordResetForm extends SpecialPage { } /** - * @throws PasswordError + * @throws PasswordError when cannot set the new password because requirements not met. */ function attemptReset( $newpass, $retype ) { $user = User::newFromName( $this->mName ); diff --git a/includes/SpecialUncategorizedimages.php b/includes/SpecialUncategorizedimages.php index 7c916770a1..22e3466914 100644 --- a/includes/SpecialUncategorizedimages.php +++ b/includes/SpecialUncategorizedimages.php @@ -3,7 +3,7 @@ /** * Special page lists images which haven't been categorised * - * @addtogroup Special pages + * @addtogroup SpecialPage * @author Rob Church */ diff --git a/includes/SpecialUndelete.php b/includes/SpecialUndelete.php index 36d36690af..5437d2a462 100644 --- a/includes/SpecialUndelete.php +++ b/includes/SpecialUndelete.php @@ -4,7 +4,7 @@ * Special page allowing users with the appropriate permissions to view * and restore deleted content * - * @addtogroup Special pages + * @addtogroup SpecialPage */ /** diff --git a/includes/SpecialUnusedtemplates.php b/includes/SpecialUnusedtemplates.php index e31c10f9d5..033066dbcf 100644 --- a/includes/SpecialUnusedtemplates.php +++ b/includes/SpecialUnusedtemplates.php @@ -1,17 +1,11 @@ * @copyright © 2006 Rob Church * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License 2.0 or later - */ - -/** * @addtogroup SpecialPage */ - class UnusedtemplatesPage extends QueryPage { function getName() { return( 'Unusedtemplates' ); } diff --git a/includes/SpecialUserlogin.php b/includes/SpecialUserlogin.php index 879886cd65..a5f2521039 100644 --- a/includes/SpecialUserlogin.php +++ b/includes/SpecialUserlogin.php @@ -40,7 +40,7 @@ class LoginForm { /** * Constructor - * @param webrequest $request A webrequest object passed by reference + * @param WebRequest $request A WebRequest object passed by reference */ function LoginForm( &$request ) { global $wgLang, $wgAllowRealName, $wgEnableEmail; diff --git a/includes/SpecialUserrights.php b/includes/SpecialUserrights.php index 30c7945bff..7f00b1fa3f 100644 --- a/includes/SpecialUserrights.php +++ b/includes/SpecialUserrights.php @@ -3,7 +3,7 @@ /** * Special page to allow managing user group membership * - * @addtogroup Special pages + * @addtogroup SpecialPage * @todo This code is disgusting and needs a total rewrite */ diff --git a/includes/api/ApiFormatJson_json.php b/includes/api/ApiFormatJson_json.php index 91154e24dd..c15cdd8003 100644 --- a/includes/api/ApiFormatJson_json.php +++ b/includes/api/ApiFormatJson_json.php @@ -45,7 +45,6 @@ * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH * DAMAGE. * -* @category * @addtogroup Services_JSON * @author Michal Migurski * @author Matt Knapp @@ -53,7 +52,7 @@ * @copyright 2005 Michal Migurski * @version CVS: $Id: JSON.php,v 1.30 2006/03/08 16:10:20 migurski Exp $ * @license http://www.opensource.org/licenses/bsd-license.php -* @link http://pear.php.net/pepr/pepr-proposal-show.php?id=198 +* @see http://pear.php.net/pepr/pepr-proposal-show.php?id=198 */ /** diff --git a/includes/api/ApiFormatYaml_spyc.php b/includes/api/ApiFormatYaml_spyc.php index 579fa5c1e5..91155aa99c 100644 --- a/includes/api/ApiFormatYaml_spyc.php +++ b/includes/api/ApiFormatYaml_spyc.php @@ -3,7 +3,7 @@ * Spyc -- A Simple PHP YAML Class * @version 0.2.3 -- 2006-02-04 * @author Chris Wanstrath - * @link http://spyc.sourceforge.net/ + * @see http://spyc.sourceforge.net/ * @copyright Copyright 2005-2006 Chris Wanstrath * @license http://www.opensource.org/licenses/mit-license.php MIT License * @addtogroup Spyc @@ -20,7 +20,7 @@ */ var $parent; var $id; - /**#@+*/ + /**#@-*/ /** * @access public * @var mixed @@ -340,7 +340,7 @@ var $_isInline; var $_dumpIndent; var $_dumpWordWrap; - /**#@+*/ + /**#@-*/ /**** Private Methods ****/ @@ -858,4 +858,4 @@ return $ret; } } -?> \ No newline at end of file +?> diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php index 43d1da4321..214cfc747d 100644 --- a/includes/api/ApiMain.php +++ b/includes/api/ApiMain.php @@ -346,8 +346,8 @@ class ApiMain extends ApiBase { } /** -* @desc This exception will be thrown when dieUsage is called to stop module execution. -*/ + * This exception will be thrown when dieUsage is called to stop module execution. + */ class UsageException extends Exception { private $mCodestr; -- 2.20.1