EBernhardson has uploaded a new change for review.
https://gerrit.wikimedia.org/r/150375
Change subject: Hygine: Class comments for Flow\\Data\\*
......................................................................
Hygine: Class comments for Flow\\Data\\*
Change-Id: Id3f3fe88042042bfc1e20d9e2124ae70494ad0f6
---
M includes/Data/BasicObjectMapper.php
M includes/Data/BoardHistoryIndex.php
M includes/Data/BoardHistoryStorage.php
M includes/Data/CachingObjectMapper.php
M includes/Data/HeaderRecentChanges.php
M includes/Data/HeaderRevisionStorage.php
M includes/Data/OccupationListener.php
M includes/Data/OneStepUserNameQuery.php
M includes/Data/Pager.php
M includes/Data/PagerPage.php
M includes/Data/PostRevisionRecentChanges.php
M includes/Data/PostRevisionStorage.php
M includes/Data/PostSummaryRecentChanges.php
M includes/Data/PostSummaryRevisionStorage.php
M includes/Data/RawSql.php
M includes/Data/RecentChanges.php
M includes/Data/ReferenceRecorder.php
M includes/Data/RevisionStorage.php
M includes/Data/TopicHistoryStorage.php
M includes/Data/TwoStepUserNameQuery.php
M includes/Data/UserNameQuery.php
M includes/Data/WatchTopicListener.php
M includes/Data/WorkflowTopicListListener.php
23 files changed, 107 insertions(+), 14 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Flow
refs/changes/75/150375/1
diff --git a/includes/Data/BasicObjectMapper.php
b/includes/Data/BasicObjectMapper.php
index 71789c5..9728aa8 100644
--- a/includes/Data/BasicObjectMapper.php
+++ b/includes/Data/BasicObjectMapper.php
@@ -3,6 +3,12 @@
namespace Flow\Data;
/**
+ * Simplest possible implementation of ObjectMapper delgates
+ * execution to closures passed in the constructor.
+ *
+ * This can be used to keep the mapping logic in static methods
+ * within the model as so:
+ *
* $userMapper = new BasicObjectMapper(
* array( 'User', 'toStorageRow' ),
* array( 'User', 'fromStorageRow' ),
diff --git a/includes/Data/BoardHistoryIndex.php
b/includes/Data/BoardHistoryIndex.php
index dd76ff9..5391285 100644
--- a/includes/Data/BoardHistoryIndex.php
+++ b/includes/Data/BoardHistoryIndex.php
@@ -9,6 +9,10 @@
use Flow\Model\TopicListEntry;
use Flow\Exception\DataModelException;
+/**
+ * Keeps a list of revision ids relevant to the board history bucketed
+ * by the owning TopicList id (board workflow)
+ */
class BoardHistoryIndex extends TopKIndex {
public function __construct( BufferedCache $cache, BoardHistoryStorage
$storage, $prefix, array $indexed, array $options = array() ) {
diff --git a/includes/Data/BoardHistoryStorage.php
b/includes/Data/BoardHistoryStorage.php
index b1b53da..e61afa5 100644
--- a/includes/Data/BoardHistoryStorage.php
+++ b/includes/Data/BoardHistoryStorage.php
@@ -5,9 +5,13 @@
use Flow\Model\UUID;
use Flow\Exception\DataModelException;
+/**
+ * SQL backing for BoardHistoryIndex fetches revisions related
+ * to a specific TopicList(board workflow)
+ */
class BoardHistoryStorage extends DbStorage {
- function find( array $attributes, array $options = array() ) {
+ public function find( array $attributes, array $options = array() ) {
$multi = $this->findMulti( $attributes, $options );
if ( $multi ) {
return reset( $multi );
@@ -15,7 +19,7 @@
return null;
}
- function findMulti( array $queries, array $options = array() ) {
+ public function findMulti( array $queries, array $options = array() ) {
if ( count( $queries ) > 1 ) {
throw new DataModelException( __METHOD__ . ' expects
only one value in $queries', 'process-data' );
}
@@ -27,7 +31,7 @@
return RevisionStorage::mergeExternalContent( array( $merged )
);
}
- function findHeaderHistory( array $queries, array $options = array() ) {
+ protected function findHeaderHistory( array $queries, array $options =
array() ) {
$queries = $this->preprocessSqlArray( reset( $queries ) );
$res = $this->dbFactory->getDB( DB_SLAVE )->select(
@@ -49,7 +53,7 @@
return $retval;
}
- function findTopicSummaryHistory( array $queries, array $options =
array() ) {
+ protected function findTopicSummaryHistory( array $queries, array
$options = array() ) {
$queries = $this->preprocessSqlArray( reset( $queries ) );
$res = $this->dbFactory->getDB( DB_SLAVE )->select(
@@ -75,7 +79,7 @@
return $retval;
}
- function findTopicListHistory( array $queries, array $options = array()
) {
+ protected function findTopicListHistory( array $queries, array $options
= array() ) {
$queries = $this->preprocessSqlArray( reset( $queries ) );
$res = $this->dbFactory->getDB( DB_SLAVE )->select(
diff --git a/includes/Data/CachingObjectMapper.php
b/includes/Data/CachingObjectMapper.php
index b5160bb..62aa822 100644
--- a/includes/Data/CachingObjectMapper.php
+++ b/includes/Data/CachingObjectMapper.php
@@ -4,6 +4,11 @@
use Flow\Model\UUID;
+/**
+ * Rows with the same primary key always return the same object
+ * from self::fromStorageRow. This means that if two parts of the
+ * code both load revision 123 they will receive the same object.
+ */
class CachingObjectMapper implements ObjectMapper {
protected $toStorageRow;
diff --git a/includes/Data/HeaderRecentChanges.php
b/includes/Data/HeaderRecentChanges.php
index a926ae4..83a198d 100644
--- a/includes/Data/HeaderRecentChanges.php
+++ b/includes/Data/HeaderRecentChanges.php
@@ -7,6 +7,9 @@
use Flow\Parsoid\Utils;
use Language;
+/**
+ * Create mediawiki recent change rows for newly created Header revisions
+ */
class HeaderRecentChanges extends RecentChanges {
/**
* @var ManagerGroup
diff --git a/includes/Data/HeaderRevisionStorage.php
b/includes/Data/HeaderRevisionStorage.php
index 65ef8ce..96c6c87 100644
--- a/includes/Data/HeaderRevisionStorage.php
+++ b/includes/Data/HeaderRevisionStorage.php
@@ -2,6 +2,9 @@
namespace Flow\Data;
+/**
+ * Generic storage implementation for Header revision instances
+ */
class HeaderRevisionStorage extends RevisionStorage {
protected function getRevType() {
return 'header';
diff --git a/includes/Data/OccupationListener.php
b/includes/Data/OccupationListener.php
index 5a89a17..244c9bf 100644
--- a/includes/Data/OccupationListener.php
+++ b/includes/Data/OccupationListener.php
@@ -6,6 +6,10 @@
use Flow\Model\Workflow;
use Flow\OccupationController;
+/**
+ * Ensures that a given workflow is occupied. This will be unnecssary
+ * once we deprecate the OccupationController white list.
+ */
class OccupationListener implements LifecycleHandler {
/** @var OccupationController **/
protected $occupationController;
diff --git a/includes/Data/OneStepUserNameQuery.php
b/includes/Data/OneStepUserNameQuery.php
index 87d75bc..54aedc9 100644
--- a/includes/Data/OneStepUserNameQuery.php
+++ b/includes/Data/OneStepUserNameQuery.php
@@ -1,12 +1,12 @@
<?php
-/**
- * Provide usernames filtered by per-wiki ipblocks. Batches together
- * database requests for multiple usernames when possible.
- */
namespace Flow\Data;
use Flow\DbFactory;
+/**
+ * Provide usernames filtered by per-wiki ipblocks. Batches together
+ * database requests for multiple usernames when possible.
+ */
class OneStepUserNameQuery implements UserNameQuery {
public function __construct( DbFactory $dbFactory ) {
$this->dbFactory = $dbFactory;
diff --git a/includes/Data/Pager.php b/includes/Data/Pager.php
index 8e99a02..11dce11 100644
--- a/includes/Data/Pager.php
+++ b/includes/Data/Pager.php
@@ -4,6 +4,9 @@
use Flow\Exception\InvalidInputException;
+/**
+ * Fetches paginated results from the OM provided in constructor
+ */
class Pager {
/**
* @var ObjectManager
diff --git a/includes/Data/PagerPage.php b/includes/Data/PagerPage.php
index 9f0770c..46b7b75 100644
--- a/includes/Data/PagerPage.php
+++ b/includes/Data/PagerPage.php
@@ -2,6 +2,9 @@
namespace Flow\Data;
+/**
+ * Represents a single page of data loaded via Flow\Data\Pager
+ */
class PagerPage {
function __construct( $results, $pagingLinkOptions, $pager ) {
$this->results = $results;
diff --git a/includes/Data/PostRevisionRecentChanges.php
b/includes/Data/PostRevisionRecentChanges.php
index 5a78969..b6b1ede 100644
--- a/includes/Data/PostRevisionRecentChanges.php
+++ b/includes/Data/PostRevisionRecentChanges.php
@@ -7,6 +7,9 @@
use Flow\Repository\TreeRepository;
use Language;
+/**
+ * Insert mw recentchange rows for newly inserted PostRevision instances
+ */
class PostRevisionRecentChanges extends RecentChanges {
/**
* @var ManagerGroup
diff --git a/includes/Data/PostRevisionStorage.php
b/includes/Data/PostRevisionStorage.php
index 44ac66c..38c55d5 100644
--- a/includes/Data/PostRevisionStorage.php
+++ b/includes/Data/PostRevisionStorage.php
@@ -7,6 +7,9 @@
use Flow\Repository\TreeRepository;
use Flow\Exception\DataModelException;
+/**
+ * SQL storage and query for PostRevision instances
+ */
class PostRevisionStorage extends RevisionStorage {
public function __construct( DbFactory $dbFactory, $externalStore,
TreeRepository $treeRepo ) {
diff --git a/includes/Data/PostSummaryRecentChanges.php
b/includes/Data/PostSummaryRecentChanges.php
index 973d5f0..37f6ae7 100644
--- a/includes/Data/PostSummaryRecentChanges.php
+++ b/includes/Data/PostSummaryRecentChanges.php
@@ -6,6 +6,9 @@
use Flow\Model\PostSummary;
use Language;
+/**
+ * Create mw recentchange rows for PostSummary instances
+ */
class PostSummaryRecentChanges extends RecentChanges {
/**
* @var ManagerGroup
diff --git a/includes/Data/PostSummaryRevisionStorage.php
b/includes/Data/PostSummaryRevisionStorage.php
index 5ec8db5..10cbd90 100644
--- a/includes/Data/PostSummaryRevisionStorage.php
+++ b/includes/Data/PostSummaryRevisionStorage.php
@@ -1,6 +1,9 @@
<?php
namespace Flow\Data;
+/**
+ * Generic storage implementation for PostSummary instances
+ */
class PostSummaryRevisionStorage extends RevisionStorage {
protected function getRevType() {
return 'post-summary';
diff --git a/includes/Data/RawSql.php b/includes/Data/RawSql.php
index d2bb9ad..afed453 100644
--- a/includes/Data/RawSql.php
+++ b/includes/Data/RawSql.php
@@ -2,6 +2,11 @@
namespace Flow\Data;
+/**
+ * Value class wraps sql to be passed into queries. Values
+ * that are not wrapped in the RawSql class are escaped to
+ * plain strings.
+ */
class RawSql {
function __construct( $sql ) {
$this->sql = $sql;
diff --git a/includes/Data/RecentChanges.php b/includes/Data/RecentChanges.php
index c1d9d98..446899f 100644
--- a/includes/Data/RecentChanges.php
+++ b/includes/Data/RecentChanges.php
@@ -9,6 +9,12 @@
use RecentChange;
use Closure;
+/**
+ * Abstract class for inserting mw recentchange rows for flow AbstractRevision
+ * instances. Each revision type must extend this class implemnting the
+ * self::onAfterInsert method which calls self::insert. Those handlers must
then
+ * be attached to the appropriate ObjectManager.
+ */
abstract class RecentChanges implements LifecycleHandler {
// Value used in rc_source field of recentchanges to identify flow
specific changes
diff --git a/includes/Data/ReferenceRecorder.php
b/includes/Data/ReferenceRecorder.php
index 9a519bc..5b17ba6 100644
--- a/includes/Data/ReferenceRecorder.php
+++ b/includes/Data/ReferenceRecorder.php
@@ -8,20 +8,25 @@
use Flow\Model\Workflow;
use Flow\Parsoid\ReferenceExtractor;
+/**
+ * Listens for new revisions to be inserted. Calculates the difference in
+ * references(URLs, images, etc) between this new version and the previous
+ * revision. Uses calculated difference to update links tables to match the
new revision.
+ */
class ReferenceRecorder implements LifecycleHandler {
protected $referenceExtractor, $storage, $linksTableUpdater;
- function __construct( ReferenceExtractor $referenceExtractor,
LinksTableUpdater $linksTableUpdater, ManagerGroup $storage ) {
+ public function __construct( ReferenceExtractor $referenceExtractor,
LinksTableUpdater $linksTableUpdater, ManagerGroup $storage ) {
$this->referenceExtractor = $referenceExtractor;
$this->linksTableUpdater = $linksTableUpdater;
$this->storage = $storage;
}
- function onAfterLoad( $object, array $old ) {
+ public function onAfterLoad( $object, array $old ) {
// Nuthin
}
- function onAfterInsert( $revision, array $new, array $metadata ) {
+ public function onAfterInsert( $revision, array $new, array $metadata )
{
$workflowId = $revision->getCollection()->getWorkflowId();
$workflow = $this->storage->get( 'Workflow', $workflowId );
@@ -123,11 +128,11 @@
return array( $addReferences, $removeReferences );
}
- function onAfterUpdate( $object, array $old, array $new, array
$metadata ) {
+ public function onAfterUpdate( $object, array $old, array $new, array
$metadata ) {
// Nuthin
}
- function onAfterRemove( $object, array $old, array $metadata ) {
+ public function onAfterRemove( $object, array $old, array $metadata ) {
// Nuthin
}
}
diff --git a/includes/Data/RevisionStorage.php
b/includes/Data/RevisionStorage.php
index 975b693..b3593f7 100644
--- a/includes/Data/RevisionStorage.php
+++ b/includes/Data/RevisionStorage.php
@@ -9,6 +9,9 @@
use Flow\Model\UUID;
use MWException;
+/**
+ * Abstract storage implementation for models extending from AbstractRevision
+ */
abstract class RevisionStorage extends DbStorage {
/**
diff --git a/includes/Data/TopicHistoryStorage.php
b/includes/Data/TopicHistoryStorage.php
index 771c2d9..37bdbfb 100644
--- a/includes/Data/TopicHistoryStorage.php
+++ b/includes/Data/TopicHistoryStorage.php
@@ -4,6 +4,11 @@
use Flow\Exception\DataModelException;
+/**
+ * Query-only storage implementation merges PostRevision and
+ * PostSummary instances to provide a full list of revisions for
+ * a topics history.
+ */
class TopicHistoryStorage implements ObjectStorage {
protected $postRevisionStorage;
diff --git a/includes/Data/TwoStepUserNameQuery.php
b/includes/Data/TwoStepUserNameQuery.php
index a792a70..b3c874e 100644
--- a/includes/Data/TwoStepUserNameQuery.php
+++ b/includes/Data/TwoStepUserNameQuery.php
@@ -8,6 +8,14 @@
use Flow\DbFactory;
use Flow\Exception\FlowException;
+/**
+ * Helper query for UserNameBatch fetches requested userIds
+ * from the wiki with two independant queries. There is
+ * a different implementation that does this in one query
+ * with a join.
+ *
+ * @todo Is TwoStep usefull? shouldn't we always use the join?
+ */
class TwoStepUserNameQuery implements UserNameQuery {
public function __construct( DbFactory $dbFactory ) {
$this->dbFactory = $dbFactory;
diff --git a/includes/Data/UserNameQuery.php b/includes/Data/UserNameQuery.php
index 4ff95f1..229ab94 100644
--- a/includes/Data/UserNameQuery.php
+++ b/includes/Data/UserNameQuery.php
@@ -5,6 +5,10 @@
*/
namespace Flow\Data;
+/**
+ * Classes implementing the interface can lookup
+ * user names based on wiki + id
+ */
Interface UserNameQuery {
/**
* @param string $wiki wiki id
diff --git a/includes/Data/WatchTopicListener.php
b/includes/Data/WatchTopicListener.php
index 8d9e4b8..2c23e69 100644
--- a/includes/Data/WatchTopicListener.php
+++ b/includes/Data/WatchTopicListener.php
@@ -8,6 +8,10 @@
use User;
use WatchedItem;
+/**
+ * Auto-watch topics when the user performs one of the actions specified
+ * in the constructor.
+ */
class WatchTopicListener {
/**
diff --git a/includes/Data/WorkflowTopicListListener.php
b/includes/Data/WorkflowTopicListListener.php
index 78d9d17..4c5acee 100644
--- a/includes/Data/WorkflowTopicListListener.php
+++ b/includes/Data/WorkflowTopicListListener.php
@@ -4,6 +4,12 @@
use Flow\Model\TopicListEntry;
+/**
+ * Every time an action is performed against something within a workflow
+ * the workflow's last_update_timestamp is updated as well. This listener
+ * passes that updated timestamp along to the topic list last updated index
+ * so that it can reorder any lists this workflow is in.
+ */
class WorkflowTopicListListener implements LifecycleHandler {
/**
--
To view, visit https://gerrit.wikimedia.org/r/150375
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id3f3fe88042042bfc1e20d9e2124ae70494ad0f6
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/Flow
Gerrit-Branch: master
Gerrit-Owner: EBernhardson <ebernhard...@wikimedia.org>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
