From a09a89b48ef6e5b40b9473d81cdd7e30c4a33474 Mon Sep 17 00:00:00 2001 From: Alexandre Emsenhuber Date: Tue, 5 Mar 2013 16:39:35 +0100 Subject: [PATCH] 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 | 36 +++++++++++++---------- includes/actions/CreditsAction.php | 3 ++ includes/actions/DeleteAction.php | 7 +++++ includes/actions/EditAction.php | 15 ++++++++++ includes/actions/HistoryAction.php | 3 ++ includes/actions/InfoAction.php | 5 ++++ includes/actions/MarkpatrolledAction.php | 5 ++++ includes/actions/ProtectAction.php | 14 +++++++++ includes/actions/PurgeAction.php | 13 +++++--- includes/actions/RawAction.php | 2 ++ includes/actions/RenderAction.php | 7 +++++ includes/actions/RevisiondeleteAction.php | 5 ++++ includes/actions/ViewAction.php | 7 +++++ includes/actions/WatchAction.php | 10 +++++++ 14 files changed, 113 insertions(+), 19 deletions(-) diff --git a/includes/actions/CachedAction.php b/includes/actions/CachedAction.php index d21f9aeb42..bfdda7b939 100644 --- a/includes/actions/CachedAction.php +++ b/includes/actions/CachedAction.php @@ -1,22 +1,8 @@ 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 @@ -33,10 +19,30 @@ * 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 { /** diff --git a/includes/actions/CreditsAction.php b/includes/actions/CreditsAction.php index d0bc22cb5d..7369755056 100644 --- a/includes/actions/CreditsAction.php +++ b/includes/actions/CreditsAction.php @@ -23,6 +23,9 @@ * @author */ +/** + * @ingroup Actions + */ class CreditsAction extends FormlessAction { public function getName() { diff --git a/includes/actions/DeleteAction.php b/includes/actions/DeleteAction.php index 3cb24e6655..db7123dbb2 100644 --- a/includes/actions/DeleteAction.php +++ b/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() { diff --git a/includes/actions/EditAction.php b/includes/actions/EditAction.php index eb261fc879..dec3d841e0 100644 --- a/includes/actions/EditAction.php +++ b/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() { diff --git a/includes/actions/HistoryAction.php b/includes/actions/HistoryAction.php index d26228a35b..23855ae83c 100644 --- a/includes/actions/HistoryAction.php +++ b/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; diff --git a/includes/actions/InfoAction.php b/includes/actions/InfoAction.php index 39b3e32780..d943f99247 100644 --- a/includes/actions/InfoAction.php +++ b/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. diff --git a/includes/actions/MarkpatrolledAction.php b/includes/actions/MarkpatrolledAction.php index ae9223f457..ff6cf13a70 100644 --- a/includes/actions/MarkpatrolledAction.php +++ b/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() { diff --git a/includes/actions/ProtectAction.php b/includes/actions/ProtectAction.php index 1b55a3ccf0..ec6648e2e7 100644 --- a/includes/actions/ProtectAction.php +++ b/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() { diff --git a/includes/actions/PurgeAction.php b/includes/actions/PurgeAction.php index 4c5171c9d0..00bb961df6 100644 --- a/includes/actions/PurgeAction.php +++ b/includes/actions/PurgeAction.php @@ -1,8 +1,6 @@ . + * 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 */ +/** + * 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; diff --git a/includes/actions/RawAction.php b/includes/actions/RawAction.php index da6ba1e65a..d1d457c0c2 100644 --- a/includes/actions/RawAction.php +++ b/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; diff --git a/includes/actions/RenderAction.php b/includes/actions/RenderAction.php index 23cae6ac0f..3d244fb3f3 100644 --- a/includes/actions/RenderAction.php +++ b/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() { diff --git a/includes/actions/RevisiondeleteAction.php b/includes/actions/RevisiondeleteAction.php index 14da2fcfec..2949fa953c 100644 --- a/includes/actions/RevisiondeleteAction.php +++ b/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() { diff --git a/includes/actions/ViewAction.php b/includes/actions/ViewAction.php index af5a67474d..e227197d25 100644 --- a/includes/actions/ViewAction.php +++ b/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() { diff --git a/includes/actions/WatchAction.php b/includes/actions/WatchAction.php index e2636452d5..ae5f76c61a 100644 --- a/includes/actions/WatchAction.php +++ b/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() { -- 2.20.1