Documentation improvements in includes/actions

- Separate file and class documentation
- Add some missing class documentation
- Fix erroneous documentation

Change-Id: I35c846ad63e837165b79456dc89d330498aebf64

includes/actions/CachedAction.php

@@ -1,4 +1,28 @@
 <?php
+/**
+ * Abstract action class with scaffolding for caching HTML and other values
+ * in a single blob.
+ *
+ * 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
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup Actions
+ * @author Jeroen De Dauw < jeroendedauw@gmail.com >
+ * @since 1.20
+ */
 
 /**
  * Abstract action class with scaffolding for caching HTML and other values
@@ -17,25 +41,7 @@
  * 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
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
- * @ingroup Action
- * @author Jeroen De Dauw < jeroendedauw@gmail.com >
- * @since 1.20
+ * @ingroup Actions
  */
 abstract class CachedAction extends FormlessAction implements ICacheHelper {
 

includes/actions/CreditsAction.php

@@ -23,6 +23,9 @@
  * @author <evan@wikitravel.org>
  */
 
+/**
+ * @ingroup Actions
+ */
 class CreditsAction extends FormlessAction {
 
 	public function getName() {

includes/actions/DeleteAction.php

@@ -23,6 +23,13 @@
  * @author Timo Tijhof
  */
 
+/**
+ * Handle page deletion
+ *
+ * This is a wrapper that will call Article::delete().
+ *
+ * @ingroup Actions
+ */
 class DeleteAction extends FormlessAction {
 
 	public function getName() {

includes/actions/EditAction.php

@@ -23,6 +23,14 @@
  * @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() {

includes/actions/HistoryAction.php

@@ -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;

includes/actions/InfoAction.php

@@ -22,6 +22,11 @@
  * @ingroup Actions
  */
 
+/**
+ * Displays information about a page.
+ *
+ * @ingroup Actions
+ */
 class InfoAction extends FormlessAction {
 	/**
 	 * Returns the name of the action this object responds to.

includes/actions/MarkpatrolledAction.php

@@ -22,6 +22,11 @@
  * @ingroup Actions
  */
 
+/**
+ * Mark a revision as patrolled on a page
+ *
+ * @ingroup Actions
+ */
 class MarkpatrolledAction extends FormlessAction {
 
 	public function getName() {

includes/actions/ProtectAction.php

@@ -23,6 +23,13 @@
  * @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() {

includes/actions/PurgeAction.php

@@ -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
@@ -20,9 +18,16 @@
  *
  * @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;

includes/actions/RawAction.php

@@ -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;

includes/actions/RenderAction.php

@@ -23,6 +23,13 @@
  * @author Timo Tijhof
  */
 
+/**
+ * Handle action=render
+ *
+ * This is a wrapper that will call Article::render().
+ *
+ * @ingroup Actions
+ */
 class RenderAction extends FormlessAction {
 
 	public function getName() {

includes/actions/RevisiondeleteAction.php

@@ -23,6 +23,11 @@
  * @author Alexandre Emsenhuber
  */
 
+/**
+ * An action that just pass the request to Special:RevisionDelete
+ *
+ * @ingroup Actions
+ */
 class RevisiondeleteAction extends FormlessAction {
 
 	public function getName() {

includes/actions/ViewAction.php

@@ -23,6 +23,13 @@
  * @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() {

includes/actions/WatchAction.php

@@ -20,6 +20,11 @@
  * @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() {