From: daniel Date: Sun, 3 Jun 2012 17:27:23 +0000 (+0200) Subject: copyediting comments X-Git-Tag: 1.31.0-rc.0~22097^2^2~150 X-Git-Url: http://git.cyclocoop.org/%22%20.%20generer_url_ecrire%28%22upgrade%22%2C%22reinstall=non%22%29%20.%20%22?a=commitdiff_plain;h=a461e48eec690d73e182bebd1874fd261ebc429b;p=lhc%2Fweb%2Fwiklou.git copyediting comments --- diff --git a/includes/Content.php b/includes/Content.php index 32c69c8dbb..d256d19381 100644 --- a/includes/Content.php +++ b/includes/Content.php @@ -1,5 +1,4 @@ model_id ) { @@ -100,7 +101,7 @@ abstract class Content { } /** - * Conveniance method that returns the ContentHandler singleton for handling the content + * Convenience method that returns the ContentHandler singleton for handling the content * model this Content object uses. * * Shorthand for ContentHandler::getForContent( $this ) @@ -114,7 +115,7 @@ abstract class Content { } /** - * Conveniance method that returns the default serialization format for the content model + * Convenience method that returns the default serialization format for the content model * model this Content object uses. * * Shorthand for $this->getContentHandler()->getDefaultFormat() @@ -128,7 +129,7 @@ abstract class Content { } /** - * Conveniance method that returns the list of serialization formats supported + * Convenience method that returns the list of serialization formats supported * for the content model model this Content object uses. * * Shorthand for $this->getContentHandler()->getSupportedFormats() @@ -176,7 +177,7 @@ abstract class Content { } /** - * Conveniance method for serializing this Content object. + * Convenience method for serializing this Content object. * * Shorthand for $this->getContentHandler()->serializeContent( $this, $format ) * @@ -219,13 +220,13 @@ abstract class Content { * * Will returns false if $that is null. * Will return true if $that === $this. - * Will return false if $that->getModleName() != $this->getModel(). + * Will return false if $that->getModelName() != $this->getModel(). * Will return false if $that->getNativeData() is not equal to $this->getNativeData(), * where the meaning of "equal" depends on the actual data model. * * Implementations should be careful to make equals() transitive and reflexive: * - * * $a->equals( $b ) <=> $b->equals( $b ) + * * $a->equals( $b ) <=> $b->equals( $a ) * * $a->equals( $b ) && $b->equals( $c ) ==> $a->equals( $c ) * * @since WD.1 @@ -257,8 +258,8 @@ abstract class Content { * * $original->getModel() === $copy->getModel() * * $original->equals( $copy ) * - * If and only if the Content object is imutable, the copy() method can and should - * return $this. That is, $copy === $original may be true, but only for imutable content + * If and only if the Content object is immutable, the copy() method can and should + * return $this. That is, $copy === $original may be true, but only for immutable content * objects. * * @since WD.1 @@ -291,12 +292,13 @@ abstract class Content { * * @return ParserOutput */ - public abstract function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ); + public abstract function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ); #TODO: move to ContentHandler; #TODO: rename to getRenderOutput() + #TODO: make RenderOutput and RenderOptions base classes /** * Returns a list of DataUpdate objects for recording information about this Content in some secondary * data store. If the optional second argument, $old, is given, the updates may model only the changes that - * need to be made to replace information about the old content with infomration about the new content. + * need to be made to replace information about the old content with information about the new content. * * This default implementation calls $this->getParserOutput( $title, null, null, false ), and then * calls getSecondaryDataUpdates( $title, $recursive ) on the resulting ParserOutput object. @@ -333,8 +335,8 @@ abstract class Content { } /** - * Construct the redirect destination from this content and return an - * array of Titles, or null if this content doesn't represent a redirect. + * Construct the redirect destination from this content and return a Title, + * or null if this content doesn't represent a redirect. * This will only return the immediate redirect target, useful for * the redirect table and other checks that don't need full recursion. * @@ -377,7 +379,7 @@ abstract class Content { * @since WD.1 * * @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 (inluded) and the second heading (excluded), etc. + * 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 exist, or null if sections are not supported */ public function getSection( $sectionId ) { @@ -459,7 +461,7 @@ abstract class Content { /** * Content object implementation for representing flat text. * - * TextContent instances are imutable + * TextContent instances are immutable * * @since WD.1 */ @@ -472,7 +474,7 @@ abstract class TextContent extends Content { } public function copy() { - return $this; #NOTE: this is ok since TextContent are imutable. + return $this; #NOTE: this is ok since TextContent are immutable. } public function getTextForSummary( $maxlength = 250 ) { @@ -550,6 +552,11 @@ abstract class TextContent extends Content { /** * Returns a generic ParserOutput object, wrapping the HTML returned by getHtml(). * + * @param Title $title context title for parsing + * @param int|null $revId revision id (the parser wants that for some reason) + * @param ParserOptions|null $options parser options + * @param bool $generateHtml whether or not to generate HTML + * * @return ParserOutput representing the HTML form of the text */ public function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ) { @@ -563,6 +570,12 @@ abstract class TextContent extends Content { return $po; } + /** + * Generates an HTML version of the content, for display. + * Used by getParserOutput() to construct a ParserOutput object + * + * @return String + */ protected abstract function getHtml( ); /** @@ -592,7 +605,7 @@ abstract class TextContent extends Content { $ota = explode( "\n", $wgContLang->segmentForDiff( $otext ) ); $nta = explode( "\n", $wgContLang->segmentForDiff( $ntext ) ); - $diffs = new Diff( $ota, $nta ); + $diff = new Diff( $ota, $nta ); return $diff; } @@ -615,13 +628,14 @@ class WikitextContent extends TextContent { /** * Returns a ParserOutput object resulting from parsing the content's text using $wgParser. * - * @since WikiData1 + * @since WD.1 * - * @param IContextSource|null $context - * @param null $revId + * @param \Title $title + * @param null $revId * @param null|ParserOptions $options - * @param bool $generateHtml + * @param bool $generateHtml * + * @internal param \IContextSource|null $context * @return ParserOutput representing the HTML form of the text */ public function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ) { @@ -639,7 +653,9 @@ class WikitextContent extends TextContent { /** * Returns the section with the given id. * - * @param String $sectionId the section's id + * @param String $section + * + * @internal param String $sectionId the section's id * @return Content|false|null the section, or false if no such section exist, or null if sections are not supported */ public function getSection( $section ) { @@ -654,9 +670,11 @@ class WikitextContent extends TextContent { /** * Replaces a section in the wikitext * - * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new" - * @param $with Content: new content of the section + * @param $section empty/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' + * + * @throws MWException * @return Content Complete article content, or null if error */ public function replaceSection( $section, Content $with, $sectionTitle = '' ) { @@ -719,7 +737,7 @@ class WikitextContent extends TextContent { * @param ParserOptions $popts * @return Content */ - public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) { + public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) { #FIXME: also needed for JS/CSS! global $wgParser, $wgConteLang; $text = $this->getNativeData(); @@ -761,11 +779,13 @@ class WikitextContent extends TextContent { /** * Returns true if this content is not a redirect, and this content's text is countable according to - * the criteria defiend by $wgArticleCountMethod. + * the criteria defined by $wgArticleCountMethod. * - * @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 + * @param Bool $hasLinks if it is known whether this content contains links, provide this information here, + * to avoid redundant parsing to find out. + * @param null|\Title $title + * + * @internal param \IContextSource $context context for parsing if necessary * * @return bool true if the content is countable */ @@ -836,6 +856,7 @@ class MessageContent extends TextContent { /** * Returns the message as rendered HTML, using the options supplied to the constructor plus "parse". + * @return String the message text, parsed */ protected function getHtml( ) { $opt = array_merge( $this->mOptions, array('parse') ); @@ -846,6 +867,8 @@ class MessageContent extends TextContent { /** * Returns the message as raw text, using the options supplied to the constructor minus "parse" and "parseinline". + * + * @return String the message text, unparsed. */ public function getNativeData( ) { $opt = array_diff( $this->mOptions, array('parse', 'parseinline') ); diff --git a/includes/ContentHandler.php b/includes/ContentHandler.php index b2d28d7a48..4a8d7bb41f 100644 --- a/includes/ContentHandler.php +++ b/includes/ContentHandler.php @@ -1,21 +1,23 @@ getNativeData(). * - * If $content is not a TextContent object, the bahaviour of this method depends on the global $wgContentHandlerTextFallback: + * If $content is not a TextContent object, the behavior of this method depends on the global $wgContentHandlerTextFallback: * * If $wgContentHandlerTextFallback is 'fail' and $content is not a TextContent object, an MWException is thrown. * * If $wgContentHandlerTextFallback is 'serialize' and $content is not a TextContent object, $content->serialize() * is called to get a string form of the content. @@ -70,7 +72,7 @@ abstract class ContentHandler { } /** - * Conveniance function for creating a Content object from a given textual representation. + * Convenience function for creating a Content object from a given textual representation. * * $text will be deserialized into a Content object of the model specified by $modelId (or, * if that is not given, $title->getContentModel()) using the given format. @@ -78,7 +80,7 @@ abstract class ContentHandler { * @since WD.1 * * @static - * @param string $text the textual represenation, will be unserialized to create the Content object + * @param string $text the textual representation, will be unserialized to create the Content object * @param Title $title the title of the page this text belongs to, required as a context for deserialization * @param null|String $modelId the model to deserialize to. If not provided, $title->getContentModel() is used. * @param null|String $format the format to use for deserialization. If not given, the model's default format is used. @@ -124,7 +126,7 @@ abstract class ContentHandler { global $wgNamespaceContentModels; // NOTE: this method must not rely on $title->getContentModel() directly or indirectly, - // because it is used to initialized the mContentModel memebr. + // because it is used to initialized the mContentModel member. $ns = $title->getNamespace(); @@ -221,7 +223,7 @@ abstract class ContentHandler { * instantiated and the class name is replaced by te resulting singleton in $wgContentHandlers. * * If no ContentHandler is defined for the desired $modelId, the ContentHandler may be provided by the - * a ContentHandlerForModelID hook. if no Contenthandler can be determined, an MWException is raised. + * a ContentHandlerForModelID hook. if no ContentHandler can be determined, an MWException is raised. * * @since WD.1 * @@ -307,7 +309,7 @@ abstract class ContentHandler { * or null of no mime type is known. * * Model names are localized using system messages. Message keys - * have the form conent-model-$id. + * have the form content-model-$id. * * @static * @param int $id the content model id, as given by a CONTENT_MODEL_XXX constant @@ -392,6 +394,8 @@ abstract class ContentHandler { * @since WD.1 * * @param int $model_id the model to check + * + * @throws MWException */ protected function checkModelID( $model_id ) { if ( $model_id !== $this->mModelID ) { @@ -422,7 +426,7 @@ abstract class ContentHandler { * * @since WD.1 * - * @return String the name of the default serialiozation format as a MIME type + * @return String the name of the default serialization format as a MIME type */ public function getDefaultFormat() { return $this->mSupportedFormats[0]; @@ -454,6 +458,8 @@ abstract class ContentHandler { * for checking whether a format provided as a parameter is actually supported. * * @param String $format the serialization format to check + * + * @throws MWException */ protected function checkFormat( $format ) { if ( !$this->isSupportedFormat( $format ) ) { @@ -471,6 +477,8 @@ abstract class ContentHandler { * * @since WD.1 * + * @param \Content $content + * * @return boolean */ public function isConsistentWithDatabase( Content $content ) { @@ -492,15 +500,16 @@ abstract class ContentHandler { } /** - * Factory + * Factory creating an appropriate DifferenceEngine for this content model. + * * @since WD.1 * - * @param $context IContextSource context to use, anything else will be ignored - * @param $old Integer old ID we want to show and diff with. - * @param $new String either 'prev' or 'next'. - * @param $rcid Integer ??? FIXME (default 0) - * @param $refreshCache boolean If set, refreshes the diff cache - * @param $unhide boolean If set, allow viewing deleted revs + * @param $context IContextSource context to use, anything else will be ignored + * @param $old Integer old ID we want to show and diff with. + * @param int|String $new String either 'prev' or 'next'. + * @param $rcid Integer ??? FIXME (default 0) + * @param $refreshCache boolean If set, refreshes the diff cache + * @param $unhide boolean If set, allow viewing deleted revs * * @return DifferenceEngine */ @@ -533,9 +542,10 @@ abstract class ContentHandler { * * @since WD.1 * - * @param $oldContent String - * @param $myContent String - * @param $yourContent String + * @param Content|String $oldContent String + * @param Content|String $myContent String + * @param Content|String $yourContent String + * * @return Content|Bool */ public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) { @@ -543,22 +553,22 @@ abstract class ContentHandler { } /** - * Return an applicable autosummary if one exists for the given edit. + * Return an applicable auto-summary if one exists for the given edit. * * @since WD.1 * * @param $oldContent Content|null: the previous text of the page. * @param $newContent Content|null: The submitted text of the page. - * @param $flags Int bitmask: a bitmask of flags submitted for the edit. + * @param $flags Int bit mask: a bit mask of flags submitted for the edit. * - * @return string An appropriate autosummary, or an empty string. + * @return string An appropriate auto-summary, or an empty string. */ public function getAutosummary( Content $oldContent = null, Content $newContent = null, $flags ) { global $wgContLang; - // Decide what kind of autosummary is needed. + // Decide what kind of auto-summary is needed. - // Redirect autosummaries + // Redirect auto-summaries /** * @var $ot Title @@ -578,7 +588,7 @@ abstract class ContentHandler { return wfMsgForContent( 'autoredircomment', $rt->getFullText(), $truncatedtext ); } - // New page autosummaries + // New page auto-summaries if ( $flags & EDIT_NEW && $newContent->getSize() > 0 ) { // If they're making a new article, give its text, truncated, in the summary. @@ -588,7 +598,7 @@ abstract class ContentHandler { return wfMsgForContent( 'autosumm-new', $truncatedtext ); } - // Blanking autosummaries + // Blanking auto-summaries if ( !empty( $oldContent ) && $oldContent->getSize() > 0 && $newContent->getSize() == 0 ) { return wfMsgForContent( 'autosumm-blank' ); } elseif ( !empty( $oldContent ) && $oldContent->getSize() > 10 * $newContent->getSize() && $newContent->getSize() < 500 ) { @@ -600,8 +610,8 @@ abstract class ContentHandler { return wfMsgForContent( 'autosumm-replace', $truncatedtext ); } - // If we reach this point, there's no applicable autosummary for our case, so our - // autosummary is empty. + // If we reach this point, there's no applicable auto-summary for our case, so our + // auto-summary is empty. return ''; } @@ -790,9 +800,10 @@ abstract class TextContentHandler extends ContentHandler { * * This text-based implementation uses wfMerge(). * - * @param $oldContent String - * @param $myContent String - * @param $yourContent String + * @param \Content|String $oldContent String + * @param \Content|String $myContent String + * @param \Content|String $yourContent String + * * @return Content|Bool */ public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {