Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of content handler stuff

Browse source 
- Split file and class documentation
- Add some missing file/class descriptions
- Add missing @ingroup Content

Change-Id: I7f7e3056570ca13a92f36a408c9b961c938f09a1
This commit is contained in:
Alexandre Emsenhuber 2012-12-20 20:44:47 +01:00
parent b6f1f03ae0
commit ddf601f7d3
12 changed files with 114 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
includes/content/AbstractContent.php
View file

@ -25,6 +25,12 @@
*
* @author Daniel Kinzler
*/
/**
* Base implementation for content objects.
*
* @ingroup Content
*/
abstract class AbstractContent implements Content {
/**

6
includes/content/Content.php
View file

@ -25,6 +25,12 @@
*
* @author Daniel Kinzler
*/
/**
* Base interface for content objects.
*
* @ingroup Content
*/
interface Content {
/**

53
includes/content/ContentHandler.php
View file

@ -1,28 +1,6 @@
<?php
/**
* Exception representing a failure to serialize or unserialize a content object.
*/
class MWContentSerializationException extends MWException {
}
/**
* A content handler knows how do deal with a specific type of content on a wiki
* page. Content is stored in the database in a serialized form (using a
* serialization format a.k.a. MIME type) and is unserialized into its native
* PHP representation (the content model), which is wrapped in an instance of
* the appropriate subclass of Content.
*
* ContentHandler instances are stateless singletons that serve, among other
* things, as a factory for Content objects. Generally, there is one subclass
* of ContentHandler and one subclass of Content for every type of content model.
*
* Some content types have a flat model, that is, their native representation
* is the same as their serialized form. Examples would be JavaScript and CSS
* code. As of now, this also applies to wikitext (MediaWiki's default content
* type), but wikitext content may be represented by a DOM or AST structure in
* the future.
* Base class for content handling.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@ -46,6 +24,35 @@ class MWContentSerializationException extends MWException {
*
* @author Daniel Kinzler
*/
/**
* Exception representing a failure to serialize or unserialize a content object.
*
* @ingroup Content
*/
class MWContentSerializationException extends MWException {
}
/**
* A content handler knows how do deal with a specific type of content on a wiki
* page. Content is stored in the database in a serialized form (using a
* serialization format a.k.a. MIME type) and is unserialized into its native
* PHP representation (the content model), which is wrapped in an instance of
* the appropriate subclass of Content.
*
* ContentHandler instances are stateless singletons that serve, among other
* things, as a factory for Content objects. Generally, there is one subclass
* of ContentHandler and one subclass of Content for every type of content model.
*
* Some content types have a flat model, that is, their native representation
* is the same as their serialized form. Examples would be JavaScript and CSS
* code. As of now, this also applies to wikitext (MediaWiki's default content
* type), but wikitext content may be represented by a DOM or AST structure in
* the future.
*
* @ingroup Content
*/
abstract class ContentHandler {
/**

8
includes/content/CssContent.php
View file

@ -1,5 +1,7 @@
<?php
/**
* Content object for CSS pages.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -22,6 +24,12 @@
*
* @author Daniel Kinzler
*/
/**
* Content object for CSS pages.
*
* @ingroup Content
*/
class CssContent extends TextContent {
public function __construct( $text ) {
parent::__construct( $text, CONTENT_MODEL_CSS );

6
includes/content/CssContentHandler.php
View file

@ -1,5 +1,7 @@
<?php
/**
* Content handler for CSS pages.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -16,10 +18,14 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @ingroup Content
*/
/**
* Content handler for CSS pages.
*
* @since 1.21
* @ingroup Content
*/
class CssContentHandler extends TextContentHandler {

11
includes/content/JavaScriptContent.php
View file

@ -1,6 +1,7 @@
<?php
/**
* Content for JavaScript pages.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -23,6 +24,12 @@
*
* @author Daniel Kinzler
*/
/**
* Content for JavaScript pages.
*
* @ingroup Content
*/
class JavaScriptContent extends TextContent {
public function __construct( $text ) {
parent::__construct( $text, CONTENT_MODEL_JAVASCRIPT );
@ -57,4 +64,4 @@ class JavaScriptContent extends TextContent {
return $html;
}
}
}

8
includes/content/JavaScriptContentHandler.php
View file

@ -1,5 +1,7 @@
<?php
/**
* Content handler for JavaScript pages.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -18,10 +20,12 @@
* @file
*/
# XXX: make ScriptContentHandler base class, do highlighting stuff there?
/**
* Content handler for JavaScript pages.
*
* @since 1.21
* @ingroup Content
* @todo make ScriptContentHandler base class, do highlighting stuff there?
*/
class JavaScriptContentHandler extends TextContentHandler {

16
includes/content/MessageContent.php
View file

@ -1,9 +1,6 @@
<?php
/**
* Wrapper allowing us to handle a system message as a Content object. Note that this is generally *not* used
* to represent content from the MediaWiki namespace, and that there is no MessageContentHandler. MessageContent
* is just intended as glue for wrapping a message programatically.
* Wrapper content object allowing to handle a system message as a Content object.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@ -27,6 +24,15 @@
*
* @author Daniel Kinzler
*/
/**
* Wrapper allowing us to handle a system message as a Content object.
* Note that this is generally *not* used to represent content from the
* MediaWiki namespace, and that there is no MessageContentHandler.
* MessageContent is just intended as glue for wrapping a message programatically.
*
* @ingroup Content
*/
class MessageContent extends AbstractContent {
/**
@ -149,4 +155,4 @@ class MessageContent extends AbstractContent {
$po = new ParserOutput( $html );
return $po;
}
}
}

11
includes/content/TextContent.php
View file

@ -1,10 +1,7 @@
<?php
/**
* Content object implementation for representing flat text.
*
* TextContent instances are immutable
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -27,6 +24,14 @@
*
* @author Daniel Kinzler
*/
/**
* Content object implementation for representing flat text.
*
* TextContent instances are immutable
*
* @ingroup Content
*/
class TextContent extends AbstractContent {
public function __construct( $text, $model_id = CONTENT_MODEL_TEXT ) {

9
includes/content/TextContentHandler.php
View file

@ -1,5 +1,7 @@
<?php
/**
* Base content handler class for flat text contents.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -15,11 +17,16 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @since 1.21
*
* @file
* @ingroup Content
*/
/**
* @since 1.21
* Base content handler implementation for flat text contents.
*
* @ingroup Content
*/
class TextContentHandler extends ContentHandler {

8
includes/content/WikitextContent.php
View file

@ -1,5 +1,7 @@
<?php
/**
* Content object for wiki text pages.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -22,6 +24,12 @@
*
* @author Daniel Kinzler
*/
/**
* Content object for wiki text pages.
*
* @ingroup Content
*/
class WikitextContent extends TextContent {
public function __construct( $text ) {

9
includes/content/WikitextContentHandler.php
View file

@ -1,5 +1,7 @@
<?php
/**
* Content handler for wiki text pages.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -15,11 +17,16 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @since 1.21
*
* @file
* @ingroup Content
*/
/**
* @since 1.21
* Content handler for wiki text pages.
*
* @ingroup Content
*/
class WikitextContentHandler extends TextContentHandler {