Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Improves code documentataion.

  • Loading branch information...
commit e297b6c2c3da98f914ed6a40264e6782e7ade61c 1 parent 181f5e5
Jim Safley authored
View
27 lib/Scripto.php
@@ -47,15 +47,15 @@ public function __construct(Scripto_Adapter_Interface $adapter, $mediawiki)
if ($mediawiki instanceof Scripto_Service_MediaWiki) {
$this->_mediawiki = $mediawiki;
} else if (is_array($mediawiki)
- && array_key_exists('api_url', $mediawiki)
- && array_key_exists('db_name', $mediawiki)) {
+ && array_key_exists('api_url', $mediawiki)
+ && array_key_exists('db_name', $mediawiki)) {
if (!isset($mediawiki['pass_cookies'])) {
$mediawiki['pass_cookies'] = true;
}
require_once 'Scripto/Service/MediaWiki.php';
- $this->_mediawiki = new Scripto_Service_MediaWiki($mediawiki['api_url'],
- $mediawiki['db_name'],
- (bool) $mediawiki['pass_cookies']);
+ $this->_mediawiki = new Scripto_Service_MediaWiki($mediawiki['api_url'],
+ $mediawiki['db_name'],
+ (bool) $mediawiki['pass_cookies']);
} else {
throw new Scripto_Exception('The provided mediawiki parameter is invalid.');
}
@@ -65,7 +65,7 @@ public function __construct(Scripto_Adapter_Interface $adapter, $mediawiki)
}
/**
- * Check whethe the specified document exists.
+ * Check whether the specified document exists in the external system.
*
* @param string|int $id The unique document identifier.
* @return bool
@@ -94,6 +94,9 @@ public function getDocument($id)
/**
* Login via the MediaWiki service.
*
+ * It is possible to restrict account creation in MediaWiki.
+ * @link http://www.mediawiki.org/wiki/Manual:Preventing_access#Restrict_account_creation
+ *
* @param string $username
* @param string $password
*/
@@ -179,7 +182,7 @@ public function getUserName()
/**
* Get the current user's most recently contributed document pages.
*
- * @param int $limit
+ * @param int $limit The number of document pages to return.
* @return array
*/
public function getUserDocumentPages($limit = 10)
@@ -254,7 +257,7 @@ public function getUserDocumentPages($limit = 10)
* Get the recent changes.
*
* @link http://www.mediawiki.org/wiki/Manual:Namespace#Built-in_namespaces
- * @param int $limit
+ * @param int $limit The number of recent changes to return.
* @return array
*/
public function getRecentChanges($limit = 10)
@@ -344,10 +347,10 @@ public function getRecentChanges($limit = 10)
/**
* Get the difference between two page revisions.
*
- * @param string $title
- * @param int $from The revision ID to diff.
- * @param int|string $to The revision to diff to: use the revision ID,
- * prev, next, or cur.
+ * @param int $from The revision ID from which to diff.
+ * @param int|string $to The revision to which to diff. Use the revision ID,
+ * "prev", "next", or "cur".
+ * @return string
*/
public function getRevisionDiff($fromRevisionId, $toRevisionId = 'prev')
{
View
2  lib/Scripto/Adapter/Example.php
@@ -147,4 +147,4 @@ public function importDocumentTranscription($documentId, $text)
{
return false;
}
-}
+}
View
2  lib/Scripto/Adapter/Exception.php
@@ -7,4 +7,4 @@
require_once 'Scripto/Exception.php';
class Scripto_Adapter_Exception extends Scripto_Exception
-{}
+{}
View
22 lib/Scripto/Adapter/Interface.php
@@ -21,9 +21,9 @@ public function documentExists($documentId);
/**
* Indicate whether the document page exists in the external system.
*
- * Implementers must provide a unique identifier for every document page. We
- * highly recommend using unique keys from the external database whenever
- * possible (e.g. the page ID).
+ * Implementers must provide a unique identifier for every document page per
+ * document. We highly recommend using unique keys from the external
+ * database whenever possible (e.g. the page ID).
*
* @param int|string $documentId The unique document ID
* @param int|string $pageId The unique page ID
@@ -34,10 +34,10 @@ public function documentPageExists($documentId, $pageId);
/**
* Get all the pages belonging to the document.
*
- * Implementers must provide a unique identifier for every page. These IDs
- * must have corresponding page names, and must be in sequential page order.
- * Page IDs must be unique but do not have to be in natural order. Page
- * names do not have to be unique.
+ * Implementers must provide a unique identifier for every page per
+ * document. These IDs must have corresponding page names, and must be in
+ * sequential page order. Page IDs must be unique but do not have to be in
+ * natural order. Page names do not have to be unique.
*
* For the page IDs we highly recommend using unique keys from the external
* database whenever possible (e.g. the file ID). This page ID will be used
@@ -57,7 +57,7 @@ public function documentPageExists($documentId, $pageId);
*
* @param int|string $documentId The unique document ID
* @return array An array containing page identifiers as keys and page names
- * as values, in sequential page order.
+ * as values, in sequential page order.
*/
public function getDocumentPages($documentId);
@@ -73,7 +73,7 @@ public function getDocumentPageImageUrl($documentId, $pageId);
/**
* Get the first page of the document.
*
- * @param int|string $documentId
+ * @param int|string $documentId The document ID
* @return int|string
*/
public function getDocumentFirstPageId($documentId);
@@ -81,7 +81,7 @@ public function getDocumentFirstPageId($documentId);
/**
* Get the title of the document.
*
- * @param int|string $documentId
+ * @param int|string $documentId The document ID
* @return string
*/
public function getDocumentTitle($documentId);
@@ -98,7 +98,7 @@ public function documentTranscriptionIsImported($documentId);
* Indicate whether the document page transcription has been imported.
*
* @param int|string $documentId The document ID
- * @param int|string $pageId Ithe page ID
+ * @param int|string $pageId The page ID
*/
public function documentPageTranscriptionIsImported($documentId, $pageId);
View
36 lib/Scripto/Document.php
@@ -47,7 +47,7 @@ class Scripto_Document
protected $_mediawiki;
/**
- * @var string This document's title.
+ * @var string The document title provided by the external system.
*/
protected $_title;
@@ -99,7 +99,10 @@ public function __construct($id,
}
/**
- * Set the current page ID and the base title used by MediaWiki.
+ * Set the current document page.
+ *
+ * Sets the current page ID, the base title used by MediaWiki, and
+ * information about the MediaWiki transcription and talk pages.
*
* @param string|null $pageId The unique page identifier.
*/
@@ -166,11 +169,14 @@ public function getPageId()
*/
public function getBaseTitle()
{
+ if (is_null($this->_pageId)) {
+ throw new Scripto_Exception('The document page must be set before getting the base title.');
+ }
return $this->_baseTitle;
}
/**
- * Get information about the current transcription page.
+ * Get information about the current MediaWiki transcription page.
*
* @return array
*/
@@ -183,7 +189,7 @@ public function getTranscriptionPageInfo()
}
/**
- * Get information about the current talk page.
+ * Get information about the current MediaWiki talk page.
*
* @return array
*/
@@ -196,18 +202,17 @@ public function getTalkPageInfo()
}
/**
- * Get the structured pages from the adapter.
+ * Get all of this document's pages from the adapter.
*
* @return array
*/
public function getPages()
{
- // Get the structured pages from the adapter.
return (array) $this->_adapter->getDocumentPages($this->_id);
}
/**
- * Get the first page ID of the document.
+ * Get this document's first page ID from the adapter.
*
* @return array
*/
@@ -217,7 +222,7 @@ public function getFirstPageId()
}
/**
- * Get the page image URL.
+ * Get this document's current page image URL from the adapter.
*
* @return string
*/
@@ -310,8 +315,8 @@ public function getTalkPagePlainText()
/**
* Get the MediaWiki transcription page revision history for the current page.
*
- * @param int $limit
- * @param int $startRevisionId Revision ID from which to start.
+ * @param int $limit The number of revisions to return.
+ * @param int $startRevisionId The revision ID from which to start.
* @return array
*/
public function getTranscriptionPageHistory($limit = 10, $startRevisionId = null)
@@ -325,8 +330,8 @@ public function getTranscriptionPageHistory($limit = 10, $startRevisionId = null
/**
* Get the MediaWiki talk page revision history for the current page.
*
- * @param int $limit
- * @param int $startRevisionId Revision ID from which to start.
+ * @param int $limit The number of revisions to return.
+ * @param int $startRevisionId The revision ID from which to start.
* @return array
*/
public function getTalkPageHistory($limit = 10, $startRevisionId = null)
@@ -343,9 +348,6 @@ public function getTalkPageHistory($limit = 10, $startRevisionId = null)
* It is possible to restrict anonymous editing in MediaWiki.
* @link http://www.mediawiki.org/wiki/Manual:Preventing_access#Restrict_editing_of_all_pages
*
- * It is possible to restrict account creation in MediaWiki.
- * @link http://www.mediawiki.org/wiki/Manual:Preventing_access#Restrict_account_creation
- *
* @return bool
*/
public function canEdit()
@@ -393,7 +395,7 @@ public function canEdit()
/**
* Edit the MediaWiki transcription page for the current document.
*
- * @param string $text The wikitext of the transcription
+ * @param string $text The wikitext of the transcription.
*/
public function editTranscriptionPage($text)
{
@@ -408,7 +410,7 @@ public function editTranscriptionPage($text)
/**
* Edit the MediaWiki talk page for the current document.
*
- * @param string $text The wikitext of the transcription
+ * @param string $text The wikitext of the transcription.
*/
public function editTalkPage($text)
{
View
2  lib/Scripto/Exception.php
@@ -5,4 +5,4 @@
*/
class Scripto_Exception extends Exception
-{}
+{}
View
2  lib/Scripto/Service/Exception.php
@@ -7,4 +7,4 @@
require_once 'Scripto/Exception.php';
class Scripto_Service_Exception extends Scripto_Exception
-{}
+{}
View
2  lib/Scripto/Service/MediaWiki.php
@@ -80,7 +80,7 @@ class Scripto_Service_MediaWiki extends Zend_Service_Abstract
/**
* Constructs the MediaWiki API client.
*
- * @param string $apiUrl
+ * @param string $apiUrl The URL to the MediaWiki API.
* @param string $dbName The name of the MediaWiki database.
* @param bool $passCookies Pass cookies to the web browser.
*/
Please sign in to comment.
Something went wrong with that request. Please try again.