From f0672924480eeed1b2c49fd46c1e795fbeb9cae9 Mon Sep 17 00:00:00 2001 From: daniel Date: Wed, 25 Apr 2012 18:56:58 +0200 Subject: [PATCH] documentation cleanup; rm unreachable code --- includes/Content.php | 75 +++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 35 deletions(-) diff --git a/includes/Content.php b/includes/Content.php index 41b7ac39a8..6f731cb7b9 100644 --- a/includes/Content.php +++ b/includes/Content.php @@ -7,7 +7,13 @@ */ abstract class Content { - // TODO: create actual fields and document them + /** + * Name of the content model this COntent object represents. + * Use with CONTENT_MODEL_XXX constants + * + * @var String $model_name + */ + protected $model_name; /** * @return String a string representing the content in a way useful for building a full text search index. @@ -18,9 +24,11 @@ abstract class Content { /** * @return String 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 for includable special pages. + * @TODO: use in parser, etc! */ - #TODO: allow native handling, bypassing wikitext representation, like for includable special pages. - public abstract function getWikitextForTransclusion( ); #FIXME: use in parser, etc! + public abstract function getWikitextForTransclusion( ); /** * Returns a textual representation of the content suitable for use in edit summaries and log messages. @@ -36,8 +44,10 @@ abstract class Content { * * @return mixed the native representation of the content. Could be a string, a nested array * structure, an object, a binary blob... anything, really. + * + * @NOTE: review all calls carefully, caller must be aware of content model! */ - public abstract function getNativeData( ); #FIXME: review all calls carefully, caller must be aware of content model! + public abstract function getNativeData( ); /** * returns the content's nominal size in bogo-bytes. @@ -47,13 +57,10 @@ abstract class Content { public abstract function getSize( ); /** - * TODO: do we really need to pass a $modelName here? - * Seems odd and makes lots of stuff hard (ie having a newEmpty static method in TextContent) - * - * @param $modelName + * @param $model_name */ - public function __construct( $modelName = null ) { - $this->mModelName = $modelName; + public function __construct( $model_name = null ) { + $this->model_name = $model_name; } /** @@ -63,16 +70,18 @@ abstract class Content { * @return String the model name */ public function getModelName() { - return $this->mModelName; + return $this->model_name; } /** - * Throws an MWException if $modelName is not the name of the content model + * Throws an MWException if $model_name is not the name of the content model * supported by this Content object. + * + * @param String $model_name the model to check */ - protected function checkModelName( $modelName ) { - if ( $modelName !== $this->mModelName ) { - throw new MWException( "Bad content model: expected " . $this->mModelName . " but got found " . $modelName ); + protected function checkModelName( $model_name ) { + if ( $model_name !== $this->model_name ) { + throw new MWException( "Bad content model: expected " . $this->model_name . " but got found " . $model_name ); } } @@ -336,11 +345,9 @@ abstract class Content { } # TODO: handle ImagePage and CategoryPage - # TODO: hook into dump generation to serialize and record model and format! - # TODO: make sure we cover lucene search / wikisearch. # TODO: make sure ReplaceTemplates still works - # TODO: nice&sane integration of GeSHi syntax highlighting + # FUTURE: nice&sane integration of GeSHi syntax highlighting # [11:59] Hooks are ugly; make CodeHighlighter interface and a config to set the class which handles syntax highlighting # [12:00] And default it to a DummyHighlighter @@ -349,10 +356,11 @@ abstract class Content { # TODO: tie into API to provide contentModel for Revisions # TODO: tie into API to provide serialized version and contentFormat for Revisions # TODO: tie into API edit interface - # TODO: make EditForm plugin for EditPage - - # XXX: isCacheable( ) # can/should we do this here? + # FUTURE: make EditForm plugin for EditPage } + # FUTURE: special type for redirects?! + # FUTURE: MultipartMultipart < WikipageContent (Main + Links + X) + # FUTURE: LinksContent < LanguageLinksContent, CategoriesContent /** * Content object implementation for representing flat text. @@ -361,8 +369,8 @@ abstract class Content { */ abstract class TextContent extends Content { - public function __construct( $text, $modelName = null ) { - parent::__construct( $modelName ); + public function __construct( $text, $model_name = null ) { + parent::__construct( $model_name ); $this->mText = $text; } @@ -384,7 +392,9 @@ abstract class TextContent extends Content { } /** - * returns the content's nominal size in bogo-bytes. + * returns the text's size in bytes. + * + * @return int the size */ public function getSize( ) { $text = $this->getNativeData( ); @@ -396,6 +406,8 @@ abstract class TextContent extends Content { * * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here, * to avoid redundant parsing to find out. + * + * @return bool true if the content is countable */ public function isCountable( $hasLinks = null ) { global $wgArticleCountMethod; @@ -426,7 +438,7 @@ abstract class TextContent extends Content { * * @return String the raw text */ - public function getTextForSearchIndex( ) { #FIXME: use! + public function getTextForSearchIndex( ) { return $this->getNativeData(); } @@ -435,7 +447,7 @@ abstract class TextContent extends Content { * * @return String the raw text */ - public function getWikitextForTransclusion( ) { #FIXME: use! + public function getWikitextForTransclusion( ) { return $this->getNativeData(); } @@ -635,6 +647,8 @@ class WikitextContent extends TextContent { * @param Bool $hasLinks if it is known whether this content contains links, provide this information here, * to avoid redundant parsing to find out. * @param IContextSource $context context for parsing if necessary + * + * @return bool true if the content is countable */ public function isCountable( $hasLinks = null, IContextSource $context = null ) { global $wgArticleCountMethod, $wgRequest; @@ -649,9 +663,6 @@ class WikitextContent extends TextContent { case 'any': return true; case 'comma': - if ( $text === false ) { - $text = $this->getRawText(); - } return strpos( $text, ',' ) !== false; case 'link': if ( $hasLinks === null ) { # not known, find out @@ -753,9 +764,3 @@ class CssContent extends TextContent { return $html; } } - -#FUTURE: special type for redirects?! -#FUTURE: MultipartMultipart < WikipageContent (Main + Links + X) -#FUTURE: LinksContent < LanguageLinksContent, CategoriesContent -#EXAMPLE: CoordinatesContent -#EXAMPLE: WikidataContent -- 2.20.1