/**
* @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
*
* @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 );
public function getNativeData();
/**
- * Returns the content's nominal size in bogo-bytes.
+ * Returns the content's nominal size in "bogo-bytes".
*
* @return int
*/
*
* @since 1.21
*
- * @return String The model id
+ * @return string The model id
*/
public function getModel();
*
* @since 1.21
*
- * @return String
+ * @return string
*/
public function getDefaultFormat();
*
* @since 1.21
*
- * @return Array of supported serialization formats
+ * @return string[] List of supported serialization formats
*/
public function getSupportedFormats();
*
* @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 );
*
* @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 );
*
* @since 1.21
*
- * @return boolean
+ * @return bool
*/
public function isValid();
*
* @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 );
*
* @since 1.21
*
- * @return Content. A copy of this object
+ * @return Content A copy of this object
*/
public function copy();
* @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 );
* 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.
*
*
* @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
/**
* 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
*
* @since 1.21
*
- * @return Array of Titles, with the destination last
+ * @return Title[]|null List of Titles, with the destination last.
*/
public function getRedirectChain();
*
* @since 1.21
*
- * @return Title: The corresponding Title
+ * @return Title|null The corresponding Title.
*/
public function getRedirectTarget();
*
* @since 1.21
*
- * @return Title
+ * @return Title|null
*/
public function getUltimateRedirectTarget();
*
* @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 );
*
* @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 );
*
* @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
*
* @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 );
*
* @since 1.21
*
- * @param $header string
+ * @param string $header
+ *
* @return Content
*/
public function addSectionHeader( $header );
*
* @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
* 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 );
*
* @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,
*
* @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 );
* 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
+
}
dépôts / lhc / web / wiklou.git / blobdiff