From 0d84b20a7c6a3b31e139810e66ea55869931849b Mon Sep 17 00:00:00 2001
From: Aaron Schulz <aschulz@wikimedia.org>
Date: Sat, 7 Mar 2015 13:39:07 -0800
Subject: [PATCH] Added clarifying comments to IContextSource

* Also removed some duplicated comments

Change-Id: I2c967d0f3219f3533378ecd5f9fccc40c8f9b219
---
 includes/context/ContextSource.php     |  6 ++----
 includes/context/DerivativeContext.php |  5 +----
 includes/context/IContextSource.php    | 28 +++++++++++++++++++++++---
 includes/context/RequestContext.php    |  2 --
 4 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/includes/context/ContextSource.php b/includes/context/ContextSource.php
index 076504ecad..83e8ef6448 100644
--- a/includes/context/ContextSource.php
+++ b/includes/context/ContextSource.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Request-dependant objects containers.
- *
  * 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
@@ -17,8 +15,6 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
- * @since 1.18
- *
  * @author Happy-melon
  * @file
  */
@@ -26,6 +22,8 @@
 /**
  * The simplest way of implementing IContextSource is to hold a RequestContext as a
  * member variable and provide accessors to it.
+ *
+ * @since 1.18
  */
 abstract class ContextSource implements IContextSource {
 	/**
diff --git a/includes/context/DerivativeContext.php b/includes/context/DerivativeContext.php
index b8966f0cf5..836aef98b4 100644
--- a/includes/context/DerivativeContext.php
+++ b/includes/context/DerivativeContext.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Request-dependant objects containers.
- *
  * 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
@@ -17,8 +15,6 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
- * @since 1.19
- *
  * @author Daniel Friesen
  * @file
  */
@@ -28,6 +24,7 @@
  * but allow individual pieces of context to be changed locally
  * eg: A ContextSource that can inherit from the main RequestContext but have
  *     a different Title instance set on it.
+ * @since 1.19
  */
 class DerivativeContext extends ContextSource {
 	/**
diff --git a/includes/context/IContextSource.php b/includes/context/IContextSource.php
index f718103d45..925666dd9a 100644
--- a/includes/context/IContextSource.php
+++ b/includes/context/IContextSource.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Request-dependant objects containers.
- *
  * 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
@@ -24,7 +22,31 @@
  */
 
 /**
- * Interface for objects which can provide a context on request.
+ * Interface for objects which can provide a MediaWiki context on request
+ *
+ * Context objects contain request-dependent objects that manage the core
+ * web request/response logic for essentially all requests to MediaWiki.
+ * The contained objects include:
+ *   a) Key objects that depend (for construction/loading) on the HTTP request
+ *   b) Key objects used for response building and PHP session state control
+ *   c) The site configuration object
+ * All of the objects are useful for the vast majority of MediaWiki requests.
+ * The site configuration object is included on grounds of extreme
+ * utility, even though it should not actually depend on the web request.
+ *
+ * More specifically, the scope of the context includes:
+ *   a) Objects that represent the HTTP request/response and PHP session state
+ *   b) Object representing the MediaWiki user (as determined by the HTTP request)
+ *   c) Primary MediaWiki output builder objects (OutputPage, user skin object)
+ *   d) The language object for the user/request
+ *   e) The title and wiki page objects requested via URL (if any)
+ *   f) The site configuration object
+ *
+ * This class is not intended as a service-locator nor a service singleton.
+ * Objects that only depend on site configuration do not belong here (aside
+ * from Config itself). Objects that represent persistent data stores do not
+ * belong here either. Session state changes should only be propagated on
+ * shutdown by separate persistence handler objects, for example.
  */
 interface IContextSource {
 	/**
diff --git a/includes/context/RequestContext.php b/includes/context/RequestContext.php
index 89a0f3deb5..3abc986921 100644
--- a/includes/context/RequestContext.php
+++ b/includes/context/RequestContext.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Container for request-dependant objects and site configuration
- *
  * 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
-- 
2.20.1