summaryrefslogtreecommitdiff
path: root/includes/content/Content.php
diff options
context:
space:
mode:
Diffstat (limited to 'includes/content/Content.php')
-rw-r--r--includes/content/Content.php163
1 files changed, 89 insertions, 74 deletions
diff --git a/includes/content/Content.php b/includes/content/Content.php
index 5a90e092..61b9254f 100644
--- a/includes/content/Content.php
+++ b/includes/content/Content.php
@@ -48,7 +48,7 @@ interface Content {
/**
* @since 1.21
*
- * @return string|false The wikitext to include when another page includes this
+ * @return string|bool The wikitext to include when another page includes this
* content, or false if the content is not includable in a wikitext page.
*
* @todo Allow native handling, bypassing wikitext representation, like
@@ -65,8 +65,9 @@ interface Content {
*
* @since 1.21
*
- * @param int $maxLength Maximum length of the summary text
- * @return string The summary text
+ * @param int $maxLength Maximum length of the summary text.
+ *
+ * @return string The summary text.
*/
public function getTextForSummary( $maxLength = 250 );
@@ -85,7 +86,7 @@ interface Content {
public function getNativeData();
/**
- * Returns the content's nominal size in bogo-bytes.
+ * Returns the content's nominal size in "bogo-bytes".
*
* @return int
*/
@@ -97,7 +98,7 @@ interface Content {
*
* @since 1.21
*
- * @return String The model id
+ * @return string The model id
*/
public function getModel();
@@ -121,7 +122,7 @@ interface Content {
*
* @since 1.21
*
- * @return String
+ * @return string
*/
public function getDefaultFormat();
@@ -133,7 +134,7 @@ interface Content {
*
* @since 1.21
*
- * @return Array of supported serialization formats
+ * @return string[] List of supported serialization formats
*/
public function getSupportedFormats();
@@ -148,7 +149,8 @@ interface Content {
*
* @since 1.21
*
- * @param string $format The format to check
+ * @param string $format The serialization format to check.
+ *
* @return bool Whether the format is supported
*/
public function isSupportedFormat( $format );
@@ -160,9 +162,9 @@ interface Content {
*
* @since 1.21
*
- * @param $format null|string The desired serialization format (or null for
- * the default format).
- * @return string Serialized form of this Content object
+ * @param string $format The desired serialization format, or null for the default format.
+ *
+ * @return string Serialized form of this Content object.
*/
public function serialize( $format = null );
@@ -185,7 +187,7 @@ interface Content {
*
* @since 1.21
*
- * @return boolean
+ * @return bool
*/
public function isValid();
@@ -208,7 +210,8 @@ interface Content {
*
* @since 1.21
*
- * @param $that Content The Content object to compare to
+ * @param Content $that The Content object to compare to.
+ *
* @return bool True if this Content object is equal to $that, false otherwise.
*/
public function equals( Content $that = null );
@@ -229,7 +232,7 @@ interface Content {
*
* @since 1.21
*
- * @return Content. A copy of this object
+ * @return Content A copy of this object
*/
public function copy();
@@ -243,7 +246,8 @@ interface Content {
* @param bool $hasLinks If it is known whether this content contains
* links, provide this information here, to avoid redundant parsing to
* find out.
- * @return boolean
+ *
+ * @return bool
*/
public function isCountable( $hasLinks = null );
@@ -253,10 +257,14 @@ interface Content {
* is needed, $generateHtml can be set to false; in that case,
* $result->getText() may return null.
*
- * @param $title Title The page title to use as a context for rendering
- * @param $revId null|int The revision being rendered (optional)
- * @param $options null|ParserOptions Any parser options
- * @param $generateHtml Boolean Whether to generate HTML (default: true). If false,
+ * @note To control which options are used in the cache key for the
+ * generated parser output, implementations of this method
+ * may call ParserOutput::recordOption() on the output object.
+ *
+ * @param Title $title The page title to use as a context for rendering.
+ * @param int $revId Optional revision ID being rendered.
+ * @param ParserOptions $options Any parser options.
+ * @param bool $generateHtml Whether to generate HTML (default: true). If false,
* the result of calling getText() on the ParserOutput object returned by
* this method is undefined.
*
@@ -264,9 +272,9 @@ interface Content {
*
* @return ParserOutput
*/
- public function getParserOutput( Title $title,
- $revId = null,
+ public function getParserOutput( Title $title, $revId = null,
ParserOptions $options = null, $generateHtml = true );
+
// TODO: make RenderOutput and RenderOptions base classes
/**
@@ -284,24 +292,22 @@ interface Content {
* Subclasses may implement this to determine the necessary updates more
* efficiently, or make use of information about the old content.
*
- * @param $title Title The context for determining the necessary updates
- * @param $old Content|null An optional Content object representing the
+ * @param Title $title The context for determining the necessary updates
+ * @param Content $old An optional Content object representing the
* previous content, i.e. the content being replaced by this Content
* object.
- * @param $recursive boolean Whether to include recursive updates (default:
+ * @param bool $recursive Whether to include recursive updates (default:
* false).
- * @param $parserOutput ParserOutput|null Optional ParserOutput object.
+ * @param ParserOutput $parserOutput Optional ParserOutput object.
* Provide if you have one handy, to avoid re-parsing of the content.
*
- * @return Array. A list of DataUpdate objects for putting information
+ * @return DataUpdate[] A list of DataUpdate objects for putting information
* about this content object somewhere.
*
* @since 1.21
*/
- public function getSecondaryDataUpdates( Title $title,
- Content $old = null,
- $recursive = true, ParserOutput $parserOutput = null
- );
+ public function getSecondaryDataUpdates( Title $title, Content $old = null,
+ $recursive = true, ParserOutput $parserOutput = null );
/**
* Construct the redirect destination from this content and return an
@@ -311,7 +317,7 @@ interface Content {
*
* @since 1.21
*
- * @return Array of Titles, with the destination last
+ * @return Title[]|null List of Titles, with the destination last.
*/
public function getRedirectChain();
@@ -323,7 +329,7 @@ interface Content {
*
* @since 1.21
*
- * @return Title: The corresponding Title
+ * @return Title|null The corresponding Title.
*/
public function getRedirectTarget();
@@ -340,7 +346,7 @@ interface Content {
*
* @since 1.21
*
- * @return Title
+ * @return Title|null
*/
public function getUltimateRedirectTarget();
@@ -360,9 +366,10 @@ interface Content {
*
* @since 1.21
*
- * @param Title $target the new redirect target
+ * @param Title $target The new redirect target
*
- * @return Content a new Content object with the updated redirect (or $this if this Content object isn't a redirect)
+ * @return Content A new Content object with the updated redirect (or $this
+ * if this Content object isn't a redirect)
*/
public function updateRedirect( Title $target );
@@ -371,11 +378,11 @@ interface Content {
*
* @since 1.21
*
- * @param string $sectionId The section's ID, given as a numeric string.
- * The ID "0" retrieves the section before the first heading, "1" the
- * text between the first heading (included) and the second heading
- * (excluded), etc.
- * @return Content|Boolean|null The section, or false if no such section
+ * @param string|number $sectionId Section identifier as a number or string
+ * (e.g. 0, 1 or 'T-1'). The ID "0" retrieves the section before the first heading, "1" the
+ * text between the first heading (included) and the second heading (excluded), etc.
+ *
+ * @return Content|bool|null The section, or false if no such section
* exist, or null if sections are not supported.
*/
public function getSection( $sectionId );
@@ -386,12 +393,15 @@ interface Content {
*
* @since 1.21
*
- * @param $section null/false or a section number (0, 1, 2, T1, T2...), or "new"
- * @param $with Content: new content of the section
- * @param string $sectionTitle new section's subject, only if $section is 'new'
- * @return string Complete article text, or null if error
+ * @param string|number|null|bool $sectionId Section identifier as a number or string
+ * (e.g. 0, 1 or 'T-1'), null/false or an empty string for the whole page
+ * or 'new' for a new section.
+ * @param Content $with New content of the section
+ * @param string $sectionTitle New section's subject, only if $section is 'new'
+ *
+ * @return string|null Complete article text, or null if error
*/
- public function replaceSection( $section, Content $with, $sectionTitle = '' );
+ public function replaceSection( $sectionId, Content $with, $sectionTitle = '' );
/**
* Returns a Content object with pre-save transformations applied (or this
@@ -399,9 +409,10 @@ interface Content {
*
* @since 1.21
*
- * @param $title Title
- * @param $user User
- * @param $parserOptions null|ParserOptions
+ * @param Title $title
+ * @param User $user
+ * @param ParserOptions $parserOptions
+ *
* @return Content
*/
public function preSaveTransform( Title $title, User $user, ParserOptions $parserOptions );
@@ -413,7 +424,8 @@ interface Content {
*
* @since 1.21
*
- * @param $header string
+ * @param string $header
+ *
* @return Content
*/
public function addSectionHeader( $header );
@@ -424,11 +436,13 @@ interface Content {
*
* @since 1.21
*
- * @param $title Title
- * @param $parserOptions null|ParserOptions
+ * @param Title $title
+ * @param ParserOptions $parserOptions
+ * @param array $params
+ *
* @return Content
*/
- public function preloadTransform( Title $title, ParserOptions $parserOptions );
+ public function preloadTransform( Title $title, ParserOptions $parserOptions, $params = array() );
/**
* Prepare Content for saving. Called before Content is saved by WikiPage::doEditContent() and in
@@ -437,24 +451,24 @@ interface Content {
* This may be used to check the content's consistency with global state. This function should
* NOT write any information to the database.
*
- * Note that this method will usually be called inside the same transaction bracket that will be used
- * to save the new revision.
+ * Note that this method will usually be called inside the same transaction
+ * bracket that will be used to save the new revision.
*
- * Note that this method is called before any update to the page table is performed. This means that
- * $page may not yet know a page ID.
+ * Note that this method is called before any update to the page table is
+ * performed. This means that $page may not yet know a page ID.
*
* @since 1.21
*
* @param WikiPage $page The page to be saved.
- * @param int $flags bitfield for use with EDIT_XXX constants, see WikiPage::doEditContent()
- * @param int $baseRevId the ID of the current revision
- * @param User $user
+ * @param int $flags Bitfield for use with EDIT_XXX constants, see WikiPage::doEditContent()
+ * @param int $baseRevId The ID of the current revision
+ * @param User $user
*
- * @return Status A status object indicating whether the content was successfully prepared for saving.
- * If the returned status indicates an error, a rollback will be performed and the
- * transaction aborted.
+ * @return Status A status object indicating whether the content was
+ * successfully prepared for saving. If the returned status indicates
+ * an error, a rollback will be performed and the transaction aborted.
*
- * @see see WikiPage::doEditContent()
+ * @see WikiPage::doEditContent()
*/
public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user );
@@ -465,12 +479,12 @@ interface Content {
*
* @since 1.21
*
- * @param $page WikiPage the deleted page
- * @param $parserOutput null|ParserOutput optional parser output object
+ * @param WikiPage $page The deleted page
+ * @param ParserOutput $parserOutput Optional parser output object
* for efficient access to meta-information about the content object.
* Provide if you have one handy.
*
- * @return array A list of DataUpdate instances that will clean up the
+ * @return DataUpdate[] A list of DataUpdate instances that will clean up the
* database after deletion.
*/
public function getDeletionUpdates( WikiPage $page,
@@ -481,9 +495,9 @@ interface Content {
*
* @since 1.21
*
- * @param MagicWord $word the magic word to match
+ * @param MagicWord $word The magic word to match
*
- * @return bool whether this Content object matches the given magic word.
+ * @return bool Whether this Content object matches the given magic word.
*/
public function matchMagicWord( MagicWord $word );
@@ -491,18 +505,19 @@ interface Content {
* Converts this content object into another content object with the given content model,
* if that is possible.
*
- * @param string $toModel the desired content model, use the CONTENT_MODEL_XXX flags.
- * @param string $lossy flag, set to "lossy" to allow lossy conversion. If lossy conversion is
- * not allowed, full round-trip conversion is expected to work without losing information.
+ * @param string $toModel The desired content model, use the CONTENT_MODEL_XXX flags.
+ * @param string $lossy Optional flag, set to "lossy" to allow lossy conversion. If lossy
+ * conversion is not allowed, full round-trip conversion is expected to work without losing
+ * information.
*
* @return Content|bool A content object with the content model $toModel, or false if
* that conversion is not supported.
*/
public function convert( $toModel, $lossy = '' );
-
- // TODO: ImagePage and CategoryPage interfere with per-content action handlers
- // TODO: nice&sane integration of GeSHi syntax highlighting
+ // @todo ImagePage and CategoryPage interfere with per-content action handlers
+ // @todo nice&sane integration of GeSHi syntax highlighting
// [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a
// config to set the class which handles syntax highlighting
// [12:00] <vvv> And default it to a DummyHighlighter
+
}