From 73e4006ad90241ec4531147144e8dbf0accce808 Mon Sep 17 00:00:00 2001
From: daniel <daniel.kinzler@wikimedia.de>
Date: Mon, 16 Apr 2012 14:13:03 +0200
Subject: [PATCH] documenting Content class

Change-Id: Ic46783d6526002ce9006ffbe1385272782ee5221
---
 includes/Content.php | 78 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

diff --git a/includes/Content.php b/includes/Content.php
index abf8282c9b..b7dd21fd91 100644
--- a/includes/Content.php
+++ b/includes/Content.php
@@ -57,28 +57,74 @@ abstract class Content {
 		$this->mModelName = $modelName;
 	}
 
+    /**
+     * Returns the name of the content model used by this content objects.
+     * Corresponds to the CONTENT_MODEL_XXX constants.
+     *
+     * @return String the model name
+     */
 	public function getModelName() {
 		return $this->mModelName;
 	}
 
+    /**
+     * Throws an MWException if $modelName is not the name of the content model
+     * supported by this Content object.
+     */
 	protected function checkModelName( $modelName ) {
 		if ( $modelName !== $this->mModelName ) {
 			throw new MWException( "Bad content model: expected " . $this->mModelName . " but got found " . $modelName );
 		}
 	}
 
+    /**
+     * Conveniance method that returns the ContentHandler singleton for handling the content
+     * model this Content object uses.
+     *
+     * Shorthand for ContentHandler::getForContent( $this )
+     *
+     * @return ContentHandler
+     */
 	public function getContentHandler() {
 		return ContentHandler::getForContent( $this );
 	}
 
+    /**
+     * Conveniance method that returns the default serialization format for the content model
+     * model this Content object uses.
+     *
+     * Shorthand for $this->getContentHandler()->getDefaultFormat()
+     *
+     * @return ContentHandler
+     */
 	public function getDefaultFormat() {
 		return $this->getContentHandler()->getDefaultFormat();
 	}
 
+    /**
+     * Conveniance method that returns the list of serialization formats supported
+     * for the content model model this Content object uses.
+     *
+     * Shorthand for $this->getContentHandler()->getSupportedFormats()
+     *
+     * @return array of supported serialization formats
+     */
 	public function getSupportedFormats() {
 		return $this->getContentHandler()->getSupportedFormats();
 	}
 
+    /**
+     * Returns true if $format is a supported serialization format for this Content object,
+     * false if it isn't.
+     *
+     * Note that this will always return true if $format is null, because null stands for the
+     * default serialization.
+     *
+     * Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
+     *
+     * @param String $format the format to check
+     * @return bool whether the format is supported
+     */
 	public function isSupportedFormat( $format ) {
 		if ( !$format ) {
 			return true; // this means "use the default"
@@ -87,21 +133,51 @@ abstract class Content {
 		return $this->getContentHandler()->isSupportedFormat( $format );
 	}
 
+    /**
+     * Throws an MWException if $this->isSupportedFormat( $format ) doesn't return true.
+     *
+     * @param $format
+     * @throws MWException
+     */
 	protected function checkFormat( $format ) {
 		if ( !$this->isSupportedFormat( $format ) ) {
 			throw new MWException( "Format $format is not supported for content model " . $this->getModelName() );
 		}
 	}
 
+    /**
+     * Conveniance method for serializing this Content object.
+     *
+     * Shorthand for $this->getContentHandler()->serialize( $this, $format )
+     *
+     * @param null|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 ) {
 		return $this->getContentHandler()->serialize( $this, $format );
 	}
 
+    /**
+     * Returns true if this Content object represents empty content.
+     *
+     * @return bool whether this Content object is empty
+     */
     public function isEmpty() {
         return $this->getSize() == 0;
     }
 
-    public function equals( Content $that ) {
+    /**
+     * Returns true if this Content objects is conceptually equivalent to the given Content object.
+     *
+     * Will returns false if $that is null.
+     * Will return true if $that === $this.
+     *
+     * Returns false if this Content object uses a different content model than the
+     *
+     * @param Content $that the Content object to compare to
+     * @return bool true if this Content object is euzqla to $that, false otherwise.
+     */
+    public function equals( Content $that = null ) {
         if ( empty( $that ) ){ // FIXME: empty on an object?
 			return false;
 		}
-- 
2.20.1