Permalink
Browse files

Enhances documentation.

  • Loading branch information...
Jim Safley
Jim Safley committed May 19, 2011
1 parent 1982848 commit 141e5bdbda285582b9430e441dcf399946fcdc79
Showing with 46 additions and 34 deletions.
  1. +28 −24 lib/Scripto.php
  2. +12 −9 lib/Scripto/Document.php
  3. +6 −1 lib/Scripto/Service/MediaWiki.php
View
@@ -40,7 +40,7 @@ class Scripto
protected $_mediawiki;
/**
- * @var array
+ * @var array Cached information about the current user.
*/
protected $_userInfo;
@@ -49,10 +49,12 @@ class Scripto
*
* @param Scripto_Adapter_Interface $adapter The adapter object.
* @param array|Scripto_Service_MediaWiki $mediawiki If an array:
- * $mediawiki['api_url']: required; the MediaWiki API URL
- * $mediawiki['db_name']: required; the MediaWiki database name
- * $mediawiki['pass_cookies']: optional pass cookies to the web browser
- * via API client
+ * <ul>
+ * <li>$mediawiki['api_url']: required; the MediaWiki API URL</li>
+ * <li>$mediawiki['db_name']: required; the MediaWiki database name</li>
+ * <li>$mediawiki['pass_cookies']: optional pass cookies to the web
+ * browser via API client</li>
+ * </ul>
*/
public function __construct(Scripto_Adapter_Interface $adapter, $mediawiki)
{
@@ -135,8 +137,8 @@ public function getDocument($id)
* @link http://www.mediawiki.org/wiki/Manual:Preventing_access#Restrict_account_creation
*
* @uses Scripto_Service_MediaWiki::login()
- * @param string $username
- * @param string $password
+ * @param string $username The MediaWiki user's username.
+ * @param string $password The MediaWiki user's password.
*/
public function login($username, $password)
{
@@ -184,7 +186,7 @@ public function canExport(array $groups = array('sysop', 'bureaucrat'))
}
/**
- * Determine if the current user can protect the MediaWiki page.
+ * Determine if the current user can protect MediaWiki pages.
*
* @return bool
*/
@@ -399,20 +401,20 @@ public function getRecentChanges($limit = 10)
/**
* Get all documents from MediaWiki that have at least one page with text.
*
- * Returns an array with the following format:
+ * @uses Scripto_Service_MediaWiki::getAllPages()
+ * @return array An array following this format:
+ * <code>
* array(
- * [document ID] => array(
- * ["mediawiki_titles"] => array(
- * [page ID] => [mediawiki title],
- * [...]
+ * {document ID} => array(
+ * ['mediawiki_titles'] => array(
+ * {page ID} => {mediawiki title},
+ * {...}
* ),
- * ["document_title"] => [document title]
+ * ['document_title'] => {document title}
* ),
- * [...]
+ * {...}
* )
- *
- * @uses Scripto_Service_MediaWiki::getAllDocuments()
- * @return array
+ * </code>
*/
public function getAllDocuments()
{
@@ -469,10 +471,12 @@ public function getAllDocuments()
* Get the difference between two page revisions.
*
* @uses Scripto_Service_MediaWiki::getRevisionDiff()
- * @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
+ * @param int $fromRevisionId The revision ID from which to diff.
+ * @param int|string $toRevisionId The revision to which to diff. Use the
+ * revision ID, "prev", "next", or "cur".
+ * @return string An HTML table without the wrapping <table> tag containing
+ * difference markup, pre-formatted by MediaWiki. It is the responsibility
+ * of implementers to wrap the result with table tags.
*/
public function getRevisionDiff($fromRevisionId, $toRevisionId = 'prev')
{
@@ -483,7 +487,7 @@ public function getRevisionDiff($fromRevisionId, $toRevisionId = 'prev')
* Get properties of the specified page revision.
*
* @uses Scripto_Service_MediaWiki::getRevisions()
- * @param int $revisionId
+ * @param int $revisionId The ID of the rpage evision.
* @return array
*/
public function getRevision($revisionId)
@@ -516,7 +520,7 @@ public function getRevision($revisionId)
* Determine whether the provided MediaWiki API URL is valid.
*
* @uses Scripto_Service_MediaWiki::isValidApiUrl()
- * @param string $apiUrl
+ * @param string $apiUrl The MediaWiki API URL to validate.
* @return bool
*/
static public function isValidApiUrl($apiUrl)
View
@@ -67,7 +67,8 @@ class Scripto_Document
protected $_pageId;
/**
- * @var string The base title of the corresponding MediaWiki page.
+ * @var string The base title (i.e. without a namespace) of the
+ * corresponding MediaWiki page.
*/
protected $_baseTitle;
@@ -567,9 +568,6 @@ public function export($type = 'plain_text', $pageDelimiter = "\n")
/**
* Determine if the current user can edit the specified MediaWiki page.
*
- * It is possible to restrict anonymous editing in MediaWiki.
- * @link http://www.mediawiki.org/wiki/Manual:Preventing_access#Restrict_editing_of_all_pages
- *
* @uses Scripto_Service_MediaWiki::getUserInfo()
* @param array $pageProtections
* @return bool
@@ -613,7 +611,9 @@ protected function _canEdit(array $pageProtections)
/**
* Determine whether the provided protections contain an edit protection.
*
- * @param array $pageProtections The page protections from the page info.
+ * @param array $pageProtections The page protections from the page info:
+ * {@link Scripto_Document::$_transcriptionPageInfo} or
+ * {@link Scripto_Document::$_talkPageInfo}.
* @return bool
*/
protected function _isProtectedPage(array $pageProtections)
@@ -774,10 +774,13 @@ protected function _getPageHistory($title, $limit = 10, $startRevisionId = null)
* naming conventions. Encoding in Base64 allows the title to be decoded.
*
* The base title has four parts:
- * 1) A title prefix to keep MediaWiki from capitalizing the first character
- * 2) A URL-safe Base64 encoded document ID
- * 3) A delimiter between the encoded document ID and page ID
- * 4) A URL-safe Base64 encoded page ID
+ * <ol>
+ * <li>A title prefix to keep MediaWiki from capitalizing the first
+ * character</li>
+ * <li>A URL-safe Base64 encoded document ID</li>
+ * <li>A delimiter between the encoded document ID and page ID</li>
+ * <li>A URL-safe Base64 encoded page ID</li>
+ * </ol>
*
* @link http://en.wikipedia.org/wiki/Base64#URL_applications
* @link http://en.wikipedia.org/wiki/Wikipedia:Naming_conventions_%28technical_restrictions%29
@@ -45,7 +45,11 @@ class Scripto_Service_MediaWiki extends Zend_Service_Abstract
protected $_cookieSuffixes = array('_session', 'UserID', 'UserName', 'Token');
/**
- * @var array Valid MediaWiki API actions and their valid parameters.
+ * @var array Valid MediaWiki API actions and their valid parameters. This
+ * whitelist is used to prohibit invalid actions and parameters from being
+ * set to API requests.
+ * @todo Remember to add relevant actions and parameters when adding new API
+ * functionality.
*/
protected $_actions = array(
'parse' => array(
@@ -443,6 +447,7 @@ public function protect($title,
* Create or edit a given page.
*
* @link http://www.mediawiki.org/wiki/API:Edit
+ * @link http://www.mediawiki.org/wiki/Manual:Preventing_access#Restrict_editing_of_all_pages
* @param string $title
* @param string $text
* @param string|null $edittoken

0 comments on commit 141e5bd

Please sign in to comment.