Documentation improvements in includes/actions
authorAlexandre Emsenhuber <ialex.wiki@gmail.com>
Tue, 5 Mar 2013 15:39:35 +0000 (16:39 +0100)
committerAlexandre Emsenhuber <ialex.wiki@gmail.com>
Tue, 5 Mar 2013 15:39:35 +0000 (16:39 +0100)
- Separate file and class documentation
- Add some missing class documentation
- Fix erroneous documentation

Change-Id: I35c846ad63e837165b79456dc89d330498aebf64

14 files changed:
includes/actions/CachedAction.php
includes/actions/CreditsAction.php
includes/actions/DeleteAction.php
includes/actions/EditAction.php
includes/actions/HistoryAction.php
includes/actions/InfoAction.php
includes/actions/MarkpatrolledAction.php
includes/actions/ProtectAction.php
includes/actions/PurgeAction.php
includes/actions/RawAction.php
includes/actions/RenderAction.php
includes/actions/RevisiondeleteAction.php
includes/actions/ViewAction.php
includes/actions/WatchAction.php

index d21f9ae..bfdda7b 100644 (file)
@@ -1,22 +1,8 @@
 <?php
-
 /**
  * Abstract action class with scaffolding for caching HTML and other values
  * in a single blob.
  *
- * Before using any of the caching functionality, call startCache.
- * After the last call to either getCachedValue or addCachedHTML, call saveCache.
- *
- * To get a cached value or compute it, use getCachedValue like this:
- * $this->getCachedValue( $callback );
- *
- * To add HTML that should be cached, use addCachedHTML like this:
- * $this->addCachedHTML( $callback );
- *
- * The callback function is only called when needed, so do all your expensive
- * computations here. This function should returns the HTML to be cached.
- * It should not add anything to the PageOutput object!
- *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Action
+ * @ingroup Actions
  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  * @since 1.20
  */
+
+/**
+ * Abstract action class with scaffolding for caching HTML and other values
+ * in a single blob.
+ *
+ * Before using any of the caching functionality, call startCache.
+ * After the last call to either getCachedValue or addCachedHTML, call saveCache.
+ *
+ * To get a cached value or compute it, use getCachedValue like this:
+ * $this->getCachedValue( $callback );
+ *
+ * To add HTML that should be cached, use addCachedHTML like this:
+ * $this->addCachedHTML( $callback );
+ *
+ * The callback function is only called when needed, so do all your expensive
+ * computations here. This function should returns the HTML to be cached.
+ * It should not add anything to the PageOutput object!
+ *
+ * @ingroup Actions
+ */
 abstract class CachedAction extends FormlessAction implements ICacheHelper {
 
        /**
index d0bc22c..7369755 100644 (file)
@@ -23,6 +23,9 @@
  * @author <evan@wikitravel.org>
  */
 
+/**
+ * @ingroup Actions
+ */
 class CreditsAction extends FormlessAction {
 
        public function getName() {
index 3cb24e6..db7123d 100644 (file)
  * @author Timo Tijhof
  */
 
+/**
+ * Handle page deletion
+ *
+ * This is a wrapper that will call Article::delete().
+ *
+ * @ingroup Actions
+ */
 class DeleteAction extends FormlessAction {
 
        public function getName() {
index eb261fc..dec3d84 100644 (file)
  * @author Timo Tijhof
  */
 
+/**
+ * Page edition handler
+ *
+ * This is a wrapper that will call the EditPage class, or ExternalEdit
+ * if $wgUseExternalEditor is set to true and requested by the user.
+ *
+ * @ingroup Actions
+ */
 class EditAction extends FormlessAction {
 
        public function getName() {
@@ -56,6 +64,13 @@ class EditAction extends FormlessAction {
 
 }
 
+/**
+ * Edit submission handler
+ *
+ * This is the same as EditAction; except that it sets the session cookie.
+ *
+ * @ingroup Actions
+ */
 class SubmitAction extends EditAction {
 
        public function getName() {
index d26228a..23855ae 100644 (file)
@@ -20,6 +20,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup Actions
  */
 
 /**
@@ -30,6 +31,7 @@
  * Construct it by passing in an Article, and call $h->history() to print the
  * history.
  *
+ * @ingroup Actions
  */
 class HistoryAction extends FormlessAction {
        const DIR_PREV = 0;
@@ -331,6 +333,7 @@ class HistoryAction extends FormlessAction {
 
 /**
  * @ingroup Pager
+ * @ingroup Actions
  */
 class HistoryPager extends ReverseChronologicalPager {
        public $lastRow = false, $counter, $historyPage, $buttons, $conds;
index 39b3e32..d943f99 100644 (file)
  * @ingroup Actions
  */
 
+/**
+ * Displays information about a page.
+ *
+ * @ingroup Actions
+ */
 class InfoAction extends FormlessAction {
        /**
         * Returns the name of the action this object responds to.
index ae9223f..ff6cf13 100644 (file)
  * @ingroup Actions
  */
 
+/**
+ * Mark a revision as patrolled on a page
+ *
+ * @ingroup Actions
+ */
 class MarkpatrolledAction extends FormlessAction {
 
        public function getName() {
index 1b55a3c..ec6648e 100644 (file)
  * @author Timo Tijhof
  */
 
+/**
+ * Handle page protection
+ *
+ * This is a wrapper that will call Article::protect().
+ *
+ * @ingroup Actions
+ */
 class ProtectAction extends FormlessAction {
 
        public function getName() {
@@ -41,6 +48,13 @@ class ProtectAction extends FormlessAction {
 
 }
 
+/**
+ * Handle page unprotection
+ *
+ * This is a wrapper that will call Article::unprotect().
+ *
+ * @ingroup Actions
+ */
 class UnprotectAction extends ProtectAction {
 
        public function getName() {
index 4c5171c..00bb961 100644 (file)
@@ -1,8 +1,6 @@
 <?php
 /**
- * Formats credits for articles
- *
- * Copyright 2004, Evan Prodromou <evan@wikitravel.org>.
+ * User-requested page cache purging.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  *
  * @file
  * @ingroup Actions
- * @author <evan@wikitravel.org>
  */
 
+/**
+ * User-requested page cache purging.
+ *
+ * For users with 'purge', this will directly trigger the cache purging and
+ * for users without that right, it will show a confirmation form.
+ *
+ * @ingroup Actions
+ */
 class PurgeAction extends FormAction {
 
        private $redirectParams;
index da6ba1e..d1d457c 100644 (file)
@@ -29,6 +29,8 @@
 /**
  * A simple method to retrieve the plain source of an article,
  * using "action=raw" in the GET request string.
+ *
+ * @ingroup Actions
  */
 class RawAction extends FormlessAction {
        private $mGen;
index 23cae6a..3d244fb 100644 (file)
  * @author Timo Tijhof
  */
 
+/**
+ * Handle action=render
+ *
+ * This is a wrapper that will call Article::render().
+ *
+ * @ingroup Actions
+ */
 class RenderAction extends FormlessAction {
 
        public function getName() {
index 14da2fc..2949fa9 100644 (file)
  * @author Alexandre Emsenhuber
  */
 
+/**
+ * An action that just pass the request to Special:RevisionDelete
+ *
+ * @ingroup Actions
+ */
 class RevisiondeleteAction extends FormlessAction {
 
        public function getName() {
index af5a674..e227197 100644 (file)
  * @author Timo Tijhof
  */
 
+/**
+ * An action that views article content
+ *
+ * This is a wrapper that will call Article::render().
+ *
+ * @ingroup Actions
+ */
 class ViewAction extends FormlessAction {
 
        public function getName() {
index e263645..ae5f76c 100644 (file)
  * @ingroup Actions
  */
 
+/**
+ * Page addition to a user's watchlist
+ *
+ * @ingroup Actions
+ */
 class WatchAction extends FormAction {
 
        public function getName() {
@@ -148,6 +153,11 @@ class WatchAction extends FormAction {
        }
 }
 
+/**
+ * Page removal from a user's watchlist
+ *
+ * @ingroup Actions
+ */
 class UnwatchAction extends WatchAction {
 
        public function getName() {