Merge "Use Html::rawElement() instead of hardcoded string in Special:Contributions"

[lhc/web/wiklou.git] / includes / content / Content.php

diff --git a/includes/content/Content.php b/includes/content/Content.php
index d830dc7..75ac5f2 100644 (file)
--- a/includes/content/Content.php
+++ b/includes/content/Content.php
@@ -25,6 +25,12 @@
  *
  * @author Daniel Kinzler
  */
+
+/**
+ * Base interface for content objects.
+ *
+ * @ingroup Content
+ */
 interface Content {
 
        /**
@@ -42,13 +48,13 @@ interface Content {
        /**
         * @since 1.21
         *
-        * @return string The wikitext to include when another page includes this
+        * @return string|false 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
+        * @todo allow native handling, bypassing wikitext representation, like
         *    for includable special pages.
-        * @TODO: allow transclusion into other content models than Wikitext!
-        * @TODO: used in WikiPage and MessageCache to get message text. Not so
+        * @todo allow transclusion into other content models than Wikitext!
+        * @todo used in WikiPage and MessageCache to get message text. Not so
         *    nice. What should we use instead?!
         */
        public function getWikitextForTransclusion();
@@ -74,7 +80,7 @@ interface Content {
         *    string, a nested array structure, an object, a binary blob...
         *    anything, really.
         *
-        * @NOTE: Caller must be aware of content model!
+        * @note Caller must be aware of content model!
         */
        public function getNativeData();
 
@@ -241,7 +247,6 @@ interface Content {
         */
        public function isCountable( $hasLinks = null );
 
-
        /**
         * Parse the Content object and generate a ParserOutput from the result.
         * $result->getText() can be used to obtain the generated HTML. If no HTML
@@ -262,7 +267,7 @@ interface Content {
        public function getParserOutput( Title $title,
                $revId = null,
                ParserOptions $options = null, $generateHtml = true );
-       # TODO: make RenderOutput and RenderOptions base classes
+       // TODO: make RenderOutput and RenderOptions base classes
 
        /**
         * Returns a list of DataUpdate objects for recording information about this
@@ -381,7 +386,7 @@ interface Content {
         *
         * @since 1.21
         *
-        * @param $section Empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
+        * @param $section null/false or a section number (0, 1, 2, T1, T2...), or "new"
         * @param $with Content: new content of the section
         * @param $sectionTitle String: new section's subject, only if $section is 'new'
         * @return string Complete article text, or null if error
@@ -396,10 +401,10 @@ interface Content {
         *
         * @param $title Title
         * @param $user User
-        * @param $popts null|ParserOptions
+        * @param $parserOptions null|ParserOptions
         * @return Content
         */
-       public function preSaveTransform( Title $title, User $user, ParserOptions $popts );
+       public function preSaveTransform( Title $title, User $user, ParserOptions $parserOptions );
 
        /**
         * Returns a new WikitextContent object with the given section heading
@@ -420,10 +425,10 @@ interface Content {
         * @since 1.21
         *
         * @param $title Title
-        * @param $popts null|ParserOptions
+        * @param $parserOptions null|ParserOptions
         * @return Content
         */
-       public function preloadTransform( Title $title, ParserOptions $popts );
+       public function preloadTransform( Title $title, ParserOptions $parserOptions );
 
        /**
         * Prepare Content for saving. Called before Content is saved by WikiPage::doEditContent() and in
@@ -460,8 +465,8 @@ interface Content {
         *
         * @since 1.21
         *
-        * @param $page \WikiPage the deleted page
-        * @param $parserOutput null|\ParserOutput optional parser output object
+        * @param $page WikiPage the deleted page
+        * @param $parserOutput null|ParserOutput optional parser output object
         *    for efficient access to meta-information about the content object.
         *    Provide if you have one handy.
         *
@@ -482,9 +487,22 @@ interface Content {
         */
        public function matchMagicWord( MagicWord $word );
 
-       # 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
+       /**
+        * 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.
+        *
+        * @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
+       //   [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
 }