X-Git-Url: http://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2Fcontent%2FContent.php;h=75ac5f2993a2c4b3524f9c14e586f4153ff4d2b4;hb=2f5b0c4d2664ca339d2cb14a85439813c88961c7;hp=d830dc7dc25a1771c8367f5ad84b29c88c375032;hpb=22aeca2dfeb7efd3f15036cbb869d6e0b90bc3d8;p=lhc%2Fweb%2Fwiklou.git

diff --git a/includes/content/Content.php b/includes/content/Content.php
index d830dc7dc2..75ac5f2993 100644
--- 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
 }