Harej has uploaded a new change for review. (
https://gerrit.wikimedia.org/r/337375 )
Change subject: Function documentation.
......................................................................
Function documentation.
Bug: T149375
Change-Id: I5b39a14bf8e545f167a96dc0341443d85c10d02f
---
M CollaborationKit.hooks.php
M includes/CollaborationHubContentEditor.php
M includes/CollaborationListContentEditor.php
M includes/ResourceLoaderListStyleModule.php
M includes/SpecialCreateHubFeature.php
M includes/content/CollaborationHubContent.php
M includes/content/CollaborationHubContentHandler.php
M includes/content/CollaborationHubDiffEngine.php
M includes/content/CollaborationHubTOC.php
M includes/content/CollaborationKitImage.php
M includes/content/CollaborationListContent.php
M includes/content/CollaborationListContentHandler.php
M modules/ext.CollaborationKit.hubimage.js
M modules/ext.CollaborationKit.icon.js
M modules/ext.CollaborationKit.list.edit.js
M modules/ext.CollaborationKit.list.ui.js
16 files changed, 373 insertions(+), 153 deletions(-)
git pull
ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/CollaborationKit
refs/changes/75/337375/1
diff --git a/CollaborationKit.hooks.php b/CollaborationKit.hooks.php
index 3650353..ab56d6d 100644
--- a/CollaborationKit.hooks.php
+++ b/CollaborationKit.hooks.php
@@ -1,12 +1,18 @@
<?php
-// Hooks and crap
+/**
+ * Hooks to modify the default behavior of MediaWiki.
+ *
+ * @file
+ */
+
class CollaborationKitHooks {
/**
* Some extra tabs for editing
- * @param &$sktemplate SkinTemplate
- * @param &$links array
+ *
+ * @param SkinTemplate &$sktemplate
+ * @param array &$links
* @return bool
*/
public static function onSkinTemplateNavigation( &$sktemplate, &$links
) {
@@ -51,7 +57,7 @@
* lists and have them work properly, since ContentHandler does not
provide access
* to the parser when doing plain wikitext transclusion.
*
- * @param $parser Parser
+ * @param Parser $parser
*/
public static function onParserFirstCallInit( $parser ) {
$parser->setFunctionHook( 'transcludelist',
'CollaborationListContent::transcludeHook' );
@@ -63,8 +69,8 @@
* Declares JSON as the code editor language for CollaborationKit pages.
*
* This hook only runs if the CodeEditor extension is enabled.
- * @param $title Title
- * @param &$lang string Page language.
+ * @param Title $title
+ * @param string &$lang Page language.
* @return bool
*/
public static function onCodeEditorGetPageLanguage( $title, &$lang ) {
@@ -89,8 +95,8 @@
/**
* For the table of contents on subpages of a CollaborationHub
*
- * @param $out OutputPage
- * @param $text string the HTML text to be added
+ * @param OutputPage $out
+ * @param string $text the HTML text to be added
* @return bool
*/
public static function onOutputPageBeforeHTML( &$out, &$text ) {
@@ -132,8 +138,8 @@
* Eventually, the TOC will be output by onOutputPageBeforeHTML hook if
this
* hook signals it is ok.
*
- * @param $out OutputPage
- * @param $pout ParserOutput
+ * @param OutputPage $out
+ * @param ParserOutput $pout
*/
public static function onOutputPageParserOutput( OutputPage $out,
ParserOutput $pout ) {
if ( $out->getProperty( 'CollaborationHubSubpage' ) ) {
@@ -153,7 +159,7 @@
/**
* Register __NOCOLLABORATIONHUBTOC__ as a magic word.
*
- * @param &$magickWords Array All double underscore magic ids
+ * @param Array &$magicWords All double underscore magic ids
*/
public static function onGetDoubleUnderscoreIDs( array &$magicWords ) {
$magicWords[] = 'nocollaborationhubtoc';
diff --git a/includes/CollaborationHubContentEditor.php
b/includes/CollaborationHubContentEditor.php
index 8f5d75a..9af0ad8 100644
--- a/includes/CollaborationHubContentEditor.php
+++ b/includes/CollaborationHubContentEditor.php
@@ -1,7 +1,12 @@
<?php
+
/**
+ * Specialized editing interface for CollaborationHubContent pages.
+ *
* @todo Unicode unsafe browsers?
+ * @file
*/
+
class CollaborationHubContentEditor extends EditPage {
/** @var string */
@@ -27,7 +32,9 @@
}
/**
- * @param $parts array
+ * Prepares form fields.
+ *
+ * @param array $parts
* @return string html
*/
protected function getFormFields( $parts ) {
@@ -118,8 +125,9 @@
}
/**
- * Build and return the aossociative array for the content source field.
- * @param $mapping array
+ * Build and return the associative array for the content source field.
+ *
+ * @param array $mapping
* @return array
*/
protected function getOptions( $mapping ) {
@@ -157,7 +165,7 @@
* Used to set the color theme for Hub edit pages.
*
* @param OutputPage $out
- * @param Skin $sk
+ * @param Skin $skin
* @param array $bodyAttribs Attributes for the <body> element
*/
public static function setCollabkitTheme( OutputPage $out, $skin,
&$bodyAttribs ) {
@@ -175,7 +183,8 @@
/**
* Converts input from the editing form into the text/x-collabkit
* serialization used for processing the edit.
- * @param &$request WebRequest
+ *
+ * @param WebRequest &$request
* @return string|null
*/
protected function importContentFormData( &$request ) {
diff --git a/includes/CollaborationListContentEditor.php
b/includes/CollaborationListContentEditor.php
index 7dd6865..6f49384 100644
--- a/includes/CollaborationListContentEditor.php
+++ b/includes/CollaborationListContentEditor.php
@@ -1,7 +1,13 @@
<?php
+
/**
+ * Specialized editing interface for CollaborationListContent pages.
+ * Extends the notorious EditPage class.
+ *
* @todo Unicode unsafe browsers?
+ * @file
*/
+
class CollaborationListContentEditor extends EditPage {
function __construct( $page ) {
@@ -17,6 +23,9 @@
$out->addModuleStyles( 'ext.CollaborationKit.edit.styles' );
}
+ /**
+ * Prepares a modified edit form
+ */
protected function showContentForm() {
if ( $this->contentFormat !==
CollaborationListContentHandler::FORMAT_WIKI ) {
return parent::showContentForm();
@@ -63,6 +72,12 @@
$out->addHtml( Html::rawElement( 'div', [ 'class' =>
'mw-collabkit-modifiededitform' ], $partFields ) );
}
+ /**
+ * Takes contents of edit form and serializes it.
+ *
+ * @param WebRequest $request
+ * @return string
+ */
protected function importContentFormData( &$request ) {
$format = $request->getVal( 'format',
CollaborationListContentHandler::FORMAT_WIKI );
if ( $format !== CollaborationListContentHandler::FORMAT_WIKI )
{
diff --git a/includes/ResourceLoaderListStyleModule.php
b/includes/ResourceLoaderListStyleModule.php
index 77dfbff..d5029dd 100644
--- a/includes/ResourceLoaderListStyleModule.php
+++ b/includes/ResourceLoaderListStyleModule.php
@@ -1,5 +1,11 @@
<?php
+/**
+ * Class for loading ResourceLoader modules
+ *
+ * @file
+ */
+
class ResourceLoaderListStyleModule extends ResourceLoaderImageModule {
protected function getCssDeclarations( $primary, $fallback ) {
return [
diff --git a/includes/SpecialCreateHubFeature.php
b/includes/SpecialCreateHubFeature.php
index 7063467..ada0616 100644
--- a/includes/SpecialCreateHubFeature.php
+++ b/includes/SpecialCreateHubFeature.php
@@ -93,6 +93,8 @@
}
/**
+ * The result of submitting the form
+ *
* @param array $data
* @return Status
*/
@@ -232,11 +234,6 @@
// No-op: We have already redirected.
}
- /**
- * Set the form format to ooui for consistency with the rest of the ck
stuff
- * @param HTMLForm $form
- *
- */
protected function getDisplayFormat() {
return 'ooui';
}
diff --git a/includes/content/CollaborationHubContent.php
b/includes/content/CollaborationHubContent.php
index 309a9f4..586cd18 100644
--- a/includes/content/CollaborationHubContent.php
+++ b/includes/content/CollaborationHubContent.php
@@ -1,11 +1,18 @@
<?php
/**
- * Structured hub pages!
+ * A content model for group collaboration pages.
*
- * Json structure is defined in CollaborationHubContentSchema.php.
+ * The principle behind CollaborationHubContent is to facilitate
+ * the development of "WikiProjects," called "Portals" on other
+ * wikis. CollaborationHubContent facilitates the development
+ * of these nodes of activity, consisting of header content, a
+ * table of contents, and several transcluded pages.
+ * Schema is found in CollaborationHubContentSchema.php.
*
+ * @file
*/
+
class CollaborationHubContent extends JsonContent {
const HUMAN_DESC_SPLIT = "\n-----------------------\n";
@@ -36,6 +43,7 @@
/**
* 23 preset colours; actual colour values are set in the
extension.json and less modules
+ *
* @return array
*/
public static function getThemeColours() {
@@ -196,11 +204,12 @@
/**
* Fill $output with information derived from the content.
- * @param $title Title
- * @param $revId int
- * @param $options ParserOptions
- * @param $generateHtml bool
- * @param $output ParserOutput
+ *
+ * @param Title $title
+ * @param int $revId
+ * @param ParserOptions $options
+ * @param bool $generateHtml
+ * @param ParserOutput $output
*/
protected function fillParserOutput( Title $title, $revId,
ParserOptions $options,
$generateHtml, ParserOutput &$output
@@ -304,6 +313,7 @@
/**
* Helper function for fillParserOutput to get all the css classes for
the page content
+ *
* @return array
*/
protected function getHubClasses() {
@@ -324,9 +334,10 @@
/**
* Helper function for fillParserOutput
- * @param $title Title
- * @param $options ParserOptions
- * @param $membersContent CollaborationListContent|null Force-fed
member-list Content for testing purposes.
+ *
+ * @param Title $title
+ * @param ParserOptions $options
+ * @param CollaborationListContent|null $membersContent Force-fed
member-list Content for testing purposes.
* @return string
*/
protected function getMembersBlock( Title $title, ParserOptions
$options, ParserOutput $output, $membersContent = null ) {
@@ -407,9 +418,10 @@
/**
* Helper function for fillParserOutput
- * @param $title Title
- * @param $options ParserOptions
- * @param $announcementsText string Force-fed announcements HTML for
testing purposes
+ *
+ * @param Title $title
+ * @param ParserOptions $options
+ * @param string $announcementsText Force-fed announcements HTML for
testing purposes
* @return string
*/
protected function getParsedAnnouncements( Title $title, ParserOptions
$options, $announcementsText = null ) {
@@ -442,8 +454,9 @@
/**
* Helper function for fillParserOutput
- * @param $title Title
- * @param $options ParserOptions
+ *
+ * @param Title $title
+ * @param ParserOptions $options
* @return string
*/
protected function getParsedFooter( Title $title, ParserOptions
$options ) {
@@ -455,7 +468,8 @@
/**
* Get some extra buttons for another footer
- * @param $title Title
+ *
+ * @param Title $title
* @return string
*/
protected function getSecondFooter( Title $title ) {
@@ -482,10 +496,11 @@
}
/**
- * Helper function for fillParserOutput; the bulk of the actual content
- * @param $title Title
- * @param $options ParserOptions
- * @param &$output ParserOutput
+ * Helper function for fillParserOutput; the main body of the page
+ *
+ * @param Title $title
+ * @param ParserOptions $options
+ * @param ParserOutout &$output
* @return string
*/
protected function getParsedContent( Title $title, ParserOptions
$options, ParserOutput $output ) {
@@ -583,8 +598,10 @@
}
/**
- * Helper function for getParsedcontent for making subpage section
headers
- * @param $contentItem array of data for the content item we're
generating the header for
+ * Helper function for getParsedContent for making subpage section
headers
+ *
+ * @param Title $title
+ * @param array $contentItem Data for the content item we're generating
the header for
* @return string html (NOTE THIS IS AN OPEN DIV)
*/
protected function makeHeader( Title $title, array $contentItem ) {
@@ -659,10 +676,11 @@
/**
* Helper function for fillParserOutput for making editsection links in
headers
- * @param $link Target URL
- * @param $message Message to display
- * @param $icon Icon to display alongside the message, based on OOjs UI
definitions
- * @return string html
+ *
+ * @param string $link Target URL
+ * @param string $message Message to display
+ * @param string $icon Icon to display alongside the message, based on
OOjs UI definitions
+ * @return string HTML
*/
protected function makeEditSectionLink( $link, $message, $icon ) {
$html = new OOUI\ButtonWidget( [
@@ -678,8 +696,9 @@
/**
* Helper function for fillParserOutput: the table of contents
- * @param $title Title
- * @param $options ParserOptions
+ *
+ * @param Title $title
+ * @param ParserOptions $options
* @return string
*/
protected function getTableOfContents( Title $title, ParserOptions
$options ) {
@@ -689,10 +708,10 @@
/**
* Generate an image based on what's in 'image', be it an icon or a file
- * @param $fallback string for what to do for no icons - nothing,
random, specific icon...
+ *
+ * @param string $image Filename or icon name
* @param $size int for non-icon images
- * @param $seed string fallback seed for explicitly something
somethinged ones
- * @return string
+ * @return string HTML
*/
public function getParsedImage( $image, $size = 200 ) {
return CollaborationKitImage::makeImage( $image, $size, [
'fallback' => 'puzzlepiece' ] );
@@ -700,12 +719,13 @@
/**
* Find the parent hub, if any.
+ *
* Returns the first CollaborationHub Title found, even if more are
higher up, or null if none
- * @param $title Title to start looking from
- * @param $destination Title for testing purposes
- * @return Title|null
+ *
+ * @param Title $title Title to start looking from
+ * @return Title|null Title of parent hub or null if none was found
*/
- public static function getParentHub( Title $title, Title $destination =
null ) {
+ public static function getParentHub( Title $title ) {
global $wgCollaborationHubAllowedNamespaces;
$namespace = $title->getNamespace();
@@ -731,8 +751,9 @@
/**
* Converts content between wikitext and JSON.
*
- * @param $toModel string
- * @param $lossy string
+ * @param string $toModel
+ * @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
*/
public function convert( $toModel, $lossy = '' ) {
if ( $toModel === CONTENT_MODEL_WIKITEXT && $lossy === 'lossy'
) {
@@ -752,6 +773,8 @@
/**
* Convert JSON to markup that's easier for humans.
+ *
+ * @return string
*/
public function convertToHumanEditable() {
$this->decode();
@@ -773,6 +796,7 @@
/**
* Get the list of items in human editable form.
*
+ * @return string
* @todo Should this be i18n-ized?
*/
public function getHumanEditableContent() {
@@ -798,6 +822,8 @@
/**
* Escape characters used as separators in human editable mode.
*
+ * @param string $text
+ * @return string Escaped text
* @todo Unclear if this is best approach. Alternative might be
* to use 
 Or an obscure unicode character like ␊ (U+240A).
*/
@@ -821,8 +847,8 @@
/**
* Removes escape characters inserted in human editable mode.
*
- * @param $text string
- * @return string
+ * @param string $text
+ * @return string Unescaped text
*/
private static function unescapeForHumanEditable( $text ) {
$text = strtr( $text, [
@@ -836,8 +862,8 @@
/**
* Convert from human editable form into a (php) array
*
- * @param $text String text to convert
- * @return Array Result of converting it to native form
+ * @param string $text Text to convert
+ * @return array Result of converting it to native form
*/
public static function convertFromHumanEditable( $text ) {
$res = [];
@@ -863,7 +889,7 @@
/**
* Helper function that converts individual lines from
convertFromHumanEditable.
*
- * @param $line string
+ * @param string $line
* @return array
*/
private static function convertFromHumanEditableItemLine( $line ) {
@@ -897,8 +923,8 @@
/**
* Hook to use custom edit page for lists
*
- * @param $page Page
- * @param $user User
+ * @param Page $page
+ * @param User $user
*/
public static function onCustomEditor( Page $page, User $user ) {
if ( $page->getContentModel() === __CLASS__ ) {
diff --git a/includes/content/CollaborationHubContentHandler.php
b/includes/content/CollaborationHubContentHandler.php
index 71631d3..0df3534 100644
--- a/includes/content/CollaborationHubContentHandler.php
+++ b/includes/content/CollaborationHubContentHandler.php
@@ -1,5 +1,14 @@
<?php
+/**
+ * Content handler for CollaborationHubContent.
+ *
+ * We extend TextContentHandler instead of JsonContentHandler since
+ * we do not display this as JSON code except upon request.
+ *
+ * @file
+ */
+
class CollaborationHubContentHandler extends TextContentHandler {
const FORMAT_WIKI = 'text/x-collabkit';
@@ -18,7 +27,7 @@
}
/**
- * @param $title Title of page to check
+ * @param Title $title Page to check
* @return bool
*/
public function canBeUsedOn( Title $title ) {
@@ -38,8 +47,8 @@
* as that is done at a later step (to allow for outputting of invalid
content for
* debugging purposes.)
*
- * @param $text string
- * @param $format string|null
+ * @param string $text
+ * @param string|null $format
* @return CollaborationHubContent
*/
public function unserializeContent( $text, $format = null ) {
@@ -56,8 +65,8 @@
/**
* Serializes the CollaborationHubContent object.
*
- * @param $content Content
- * @param $format string|null
+ * @param Content $content
+ * @param string|null $format
* @return mixed
*/
public function serializeContent( Content $content, $format = null ) {
@@ -97,15 +106,15 @@
/**
* Edit a Collaboration Hub via the edit API
- * @param $title Title
- * @param $displayName string
- * @param $icon string
- * @param $colour string
- * @param $introduction string
- * @param $footer string
- * @param $content array
- * @param $summary string Message key for edit summary
- * @param $context IContextSource The calling context
+ * @param Title $title
+ * @param string $displayName
+ * @param string $icon
+ * @param string $colour
+ * @param string $introduction
+ * @param string $footer
+ * @param array $content
+ * @param string $summary Message key for edit summary
+ * @param IContextSource $context The calling context
* @return Status
*/
public static function edit( Title $title, $displayName, $image,
$colour, $introduction, $footer, $content, $summary, IContextSource $context ) {
diff --git a/includes/content/CollaborationHubDiffEngine.php
b/includes/content/CollaborationHubDiffEngine.php
index bb7a3e1..2ef7055 100644
--- a/includes/content/CollaborationHubDiffEngine.php
+++ b/includes/content/CollaborationHubDiffEngine.php
@@ -1,12 +1,17 @@
<?php
+/**
+ * Custom diff engine for CollaborationHubContent. Not yet implemented.
+ *
+ * @file
+ */
+
class CollaborationHubDiffEngine extends DifferenceEngine {
/**
* Implement our own diff rendering.
- * @param $old Content Old content
- * @param $new Content New content
- *
+ * @param Content $old Old content
+ * @param Content $new New content
* @throws Exception If old or new content is not an instance of
CollaborationHubContent
* @return bool|string
*/
diff --git a/includes/content/CollaborationHubTOC.php
b/includes/content/CollaborationHubTOC.php
index 5bc8606..d3ef18e 100644
--- a/includes/content/CollaborationHubTOC.php
+++ b/includes/content/CollaborationHubTOC.php
@@ -1,5 +1,11 @@
<?php
+/**
+ * Helper class to generate table of contents for CollaborationHubContent.
+ *
+ * @file
+ */
+
class CollaborationHubTOC {
/** @var $tocLinks array ids/links for ToC items that have been used
already */
@@ -7,7 +13,8 @@
/**
* Get unique id for ToC Link/header
- * @param $header
+ *
+ * @param string $header
* @return string
*/
public function getToCLinkID( $header ) {
@@ -30,9 +37,10 @@
}
/**
- * ToC rendering for hub
- * @param $content array block from collaborationhub
- * @return string html
+ * ToC rendering for CollaborationHubContent
+ *
+ * @param array $content Array block from CollaborationHubContent
+ * @return string HTML
*/
public function renderToC( $content ) {
$html = Html::openElement( 'div', [ 'class' =>
'mw-ck-toc-container' ] );
@@ -71,8 +79,9 @@
}
/**
- * ToC rendering for non-hubs
- * @param $title Title of hub the ToC is generated off
+ * ToC rendering for other pages such as subpages
+ *
+ * @param Title $title Hub the ToC is generated from
* @return string html
*/
public function renderSubpageToC( Title $title ) {
diff --git a/includes/content/CollaborationKitImage.php
b/includes/content/CollaborationKitImage.php
index 9434a44..21bb0e5 100644
--- a/includes/content/CollaborationKitImage.php
+++ b/includes/content/CollaborationKitImage.php
@@ -1,27 +1,29 @@
<?php
/**
- *
* Helper class to produce HTML elements containing images for
CollaborationKit purposes
*
+ * @file
*/
+
class CollaborationKitImage {
/**
* Generate an image element from the wiki or the extension
- * @param $image string|null The filename (no namespace prefix) or
CollaborationKit icon
+ *
+ * @param string|null $image The filename (no namespace prefix) or
CollaborationKit icon
* identifier (or null to use fallback instead)
- * @param $width int The width of the image in pixels
- * @param $options array An array with optional parameters
- * @param $options['classes'] array Array of element classes to assign
- * @param $options['link'] Title|string|bool Internal link for the
image; default is true (i.e.
+ * @param int $width The width of the image in pixels
+ * @param array $options An array with optional parameters
+ * @param array $options['classes'] Array of element classes to assign
+ * @param Title|string|bool $options['link'] Internal link for the
image; default is true (i.e.
* link to its description page). Pass `false` for no link at all.
Pass a string to link to a
* page in the manner of an internal wiki link.
- * @param $options['colour'] string The colour of the icon if using a
canned icon
- * @param $options['css'] string In-line style parameters. Avoid if
possible.
- * @param $options['renderAsWikitext'] bool Should the output be
wikitext instead of HTML?
+ * @param string $options['colour'] The colour of the icon if using a
canned icon
+ * @param string $options['css'] In-line style parameters. Avoid if
possible.
+ * @param bool $options['renderAsWikitext'] Should the output be
wikitext instead of HTML?
* Defaults to false.
- * @param $options['label'] string Label to put under image; used for
ToC icons
- * @param $options['fallback'] string If the specified image is null or
doesn't exist. Valid
+ * @param string $options['label'] Label to put under image; used for
ToC icons
+ * @param string $options['fallback'] If the specified image is null or
doesn't exist. Valid
* options are none', a valid icon ID, or an arbitrary string to
use a seed. (Note: if you
* specify a label, then that will serve as the fallback.)
* @return string HTML elements or wikitext, depending on
$options['renderAsWikitext']
@@ -83,6 +85,9 @@
return $imageBlock;
}
+ /**
+ * @return string
+ */
protected static function makeImageFromFile( $image, $classes, $width,
$link,
$renderAsWikitext, $label ) {
// This assumes that colours cannot be assigned to images.
@@ -125,6 +130,9 @@
}
}
+ /**
+ * @return string
+ */
protected static function makeImageFromIcon( $image, $classes, $width,
$colour, $link,
$renderAsWikitext, $label ) {
// Rendering as wikitext with link is not an option here due to
unfortunate behavior from Tidy.
@@ -149,6 +157,9 @@
return $imageHtml;
}
+ /**
+ * @return string
+ */
protected static function linkFactory( $imageHtml, $link, $label,
$imageObj = null ) {
// Important assumption: image is being rendered as HTML and
not wikitext.
diff --git a/includes/content/CollaborationListContent.php
b/includes/content/CollaborationListContent.php
index b04c00c..e7241a7 100644
--- a/includes/content/CollaborationListContent.php
+++ b/includes/content/CollaborationListContent.php
@@ -1,12 +1,20 @@
<?php
/**
+ * A content model for representing lists of wiki pages in JSON.
+ *
+ * This content model is used to prepare lists of pages (i.e., of
+ * members' user pages or of wiki pages to work on) and associated
+ * metadata while separating content from presentation.
+ * Features associated JavaScript modules allowing for quick
+ * manipulation of list contents.
* Important design assumption: This class assumes lists are small
* (e.g. Average case < 500 items, outliers < 2000)
- *
* Schema is found in CollaborationListContentSchema.php.
*
+ * @file
*/
+
class CollaborationListContent extends JsonContent {
const MAX_LIST_SIZE = 2000; // Maybe should be a config option.
@@ -37,6 +45,7 @@
/**
* Decode and validate the contents.
+ *
* @return bool Whether the contents are valid
*/
public function isValid() {
@@ -81,6 +90,13 @@
return false;
}
+ /**
+ * Validates a list configuration option against the schema.
+ *
+ * @param string $name The name of the parameter
+ * @param mixed $value The value of the parameter
+ * @return bool Whether the configuration option is valid.
+ */
private static function validateOption( $name, &$value ) {
$listSchema = include __DIR__ .
'/CollaborationListContentSchema.php';
@@ -108,7 +124,7 @@
}
/**
- * Format json
+ * Format JSON
*
* Do not escape < and > it's unnecessary and ugly
* @return string
@@ -120,9 +136,9 @@
/**
* Beautifies JSON and does subst: prior to save.
*
- * @param $title Title Title
- * @param $user User User
- * @param $popts ParserOptions
+ * @param Title $title
+ * @param User $user
+ * @param ParserOptions $popts
* @return CollaborationListContent
*/
public function preSaveTransform( Title $title, User $user,
ParserOptions $popts ) {
@@ -176,11 +192,12 @@
/**
* Fill $output with information derived from the content.
- * @param $title Title
- * @param $revId int
- * @param $options ParserOptions
- * @param $generateHtml bool
- * @param $output ParserOutput
+ *
+ * @param Title $title
+ * @param int $revId Revision ID
+ * @param ParserOptions $options
+ * @param bool $generateHtml
+ * @param ParserOutput $output
*/
protected function fillParserOutput( Title $title, $revId,
ParserOptions $options,
$generateHtml, ParserOutput &$output
@@ -228,7 +245,7 @@
* transclusions. They are not used when using the parser function.
*
* @todo FIXME These should maybe not be used during transclusion.
- * @return Array Options
+ * @return array Options
*/
private function getFullRenderListOptions() {
return $listOptions = [
@@ -241,8 +258,8 @@
/**
* Convert the JSON to wikitext.
*
- * @param $lang Language The (content) language to render the page in.
- * @param $options Array Options to override the default transclude
options
+ * @param Language $lang The (content) language to render the page in.
+ * @param array $options Options to override the default transclude
options
* @return string The wikitext
*/
public function convertToWikitext( Language $lang, $options = [] ) {
@@ -430,6 +447,13 @@
);
}
+ /**
+ * Converts between different text-based content models
+ *
+ * @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.
+ */
public function convert( $toModel, $lossy = '' ) {
if ( $toModel === CONTENT_MODEL_WIKITEXT && $lossy === 'lossy'
) {
global $wgContLang;
@@ -455,7 +479,7 @@
*
* Any new option must be added to this list.
*
- * @return Array default rendering options to use.
+ * @return array default rendering options to use.
*/
public function getDefaultOptions() {
// FIXME implement
@@ -476,8 +500,8 @@
/**
* Sort a list
*
- * @param &$items Array List to sort (sorted in-place)
- * @param $mode String sort method
+ * @param array &$items List to sort (sorted in-place)
+ * @param string $mode sort method
* @return Array sorted list
* @throws UnexpectedValueException on unrecognized mode
*/
@@ -517,8 +541,8 @@
/**
* Sort an array pseudo-randomly using an affine transform
*
- * @param $items Array Stuff to sort (sorted in-place)
- * @return Array
+ * @param array $items Stuff to sort (sorted in-place)
+ * @return array
*/
private function sortRandomly( &$items ) {
$totItems = count( $items );
@@ -550,9 +574,9 @@
* e.g. $tagSpecifier = [ [ 'a', 'b' ], ['b', 'd'] ]
* means that any item must have the tags (a&&b) || (b&&d).
*
- * @param $tagSpecifier Array What tags to check (aka $options['tags'])
- * @param $itemTags Array What tags is this item tagged with
- * @return boolean If the item matches
+ * @param array $tagSpecifier What tags to check (aka $options['tags'])
+ * @param array $itemTags What tags is this item tagged with
+ * @return bool If the item matches
*/
private function matchesTag( array $tagSpecifier, array $itemTags ) {
if ( !$tagSpecifier ) {
@@ -578,6 +602,7 @@
/**
* Convert JSON to markup that's easier for humans.
+ * @return string
*/
public function convertToHumanEditable() {
$this->decode();
@@ -593,7 +618,7 @@
/**
* Output the options in human readable form
*
- * @return String key=value pairs separated by newlines.
+ * @return string key=value pairs separated by newlines.
*/
private function getHumanOptions() {
$this->decode();
@@ -611,6 +636,7 @@
/**
* Get the list of items in human editable form.
*
+ * @return string
* @todo i18n-ize
*/
public function getHumanEditableList() {
@@ -669,6 +695,7 @@
/**
* Escape characters used as separators in human editable mode.
*
+ * @return string Escaped text
* @todo Unclear if this is best approach. Alternative might be
* to use 
 Or an obscure unicode character like ␊ (U+240A).
*/
@@ -689,6 +716,9 @@
return $text;
}
+ /**
+ * @return string
+ */
private static function unescapeForHumanEditable( $text ) {
$text = strtr( $text, [
'\\\\n'=> "\\n",
@@ -700,6 +730,7 @@
/**
* @param $options String Human readable options
+ * @return object
*/
private static function parseHumanOptions( $options ) {
$finalList = [];
@@ -721,8 +752,8 @@
/**
* Convert from human editable form into a (php) array
*
- * @param $text String text to convert
- * @return Array Result of converting it to native form
+ * @param string $text text to convert
+ * @return array Result of converting it to native form
*/
public static function convertFromHumanEditable( $text ) {
$res = [ 'columns' => [] ];
@@ -765,6 +796,9 @@
return $res;
}
+ /**
+ * @return array
+ */
private static function convertFromHumanEditableColumn( $column ) {
// Adding newline so that HUMAN_COLUMN_SPLIT2 correctly triggers
$column = $column . "\n";
@@ -822,6 +856,9 @@
return $columnItem;
}
+ /**
+ * @return array
+ */
private static function convertFromHumanEditableItemLine( $line ) {
$parts = explode( "|", $line );
$parts = array_map( [ __CLASS__, 'unescapeForHumanEditable' ],
$parts );
@@ -875,6 +912,10 @@
/**
* Function to handle {{#trancludelist:Page name|options...}} calls
+ *
+ * @param Parser $parser
+ * @param string $pageName
+ * @return string|array HTML string or an array [ string, 'noparse' =>
false ]
*/
public static function transcludeHook( $parser, $pageName = '' ) {
$args = func_get_args();
@@ -949,11 +990,11 @@
/**
* Sort users into active/inactive column
*
- * @param $column Array An array containing key items, which
+ * @param array $column An array containing key items, which
* is an array of stdClass's representing each list item.
* Each of these has a key named title which contains
* a user name (including namespace). May have non-users too.
- * @return Array Two column structure sorted active/inactive.
+ * @return array Two column structure sorted active/inactive.
* @todo Should link property be taken into account as actual name?
*/
private function sortUsersIntoColumns( $column ) {
@@ -992,8 +1033,8 @@
* Filter users into active and inactive.
*
* @note The results of this function get stored in parser cache.
- * @param $userList Array of user dbkeys => stdClass
- * @return Array [ 'active' => [..], 'inactive' => '[..]' ]
+ * @param array $userList Array of user dbkeys => stdClass
+ * @return array [ 'active' => [..], 'inactive' => '[..]' ]
*/
private function filterActiveUsers( $userList ) {
if ( count( $userList ) > 0 ) {
@@ -1029,9 +1070,10 @@
* So instead we put <collaborationkitloadliststyles/> on the page,
which
* calls this.
*
- * @param $content String Input to parser hook
- * @param $attribs Array
- * @param $parser Parser
+ * @param string $content Input to parser hook
+ * @param array $attribs
+ * @param Parser $parser
+ * @return string Empty string
*/
public static function loadStyles( $content, array $attributes, Parser
$parser ) {
$parser->getOutput()->addModuleStyles( [
@@ -1048,7 +1090,7 @@
* @todo Not clear if this is the best hook to use. onBeforePageDisplay
* doesn't have easy access to oldid
*
- * @param $output OutputPage
+ * @param Article $article
*/
public static function onArticleViewHeader( Article $article ) {
$title = $article->getTitle();
@@ -1075,8 +1117,9 @@
/**
* Hook to use custom edit page for lists
*
- * @param $page Page
- * @param $user User
+ * @param Page $page
+ * @param User $user
+ * @return bool
*/
public static function onCustomEditor( Page $page, User $user ) {
if ( $page->getContentModel() === __CLASS__ ) {
diff --git a/includes/content/CollaborationListContentHandler.php
b/includes/content/CollaborationListContentHandler.php
index 3fcf0b2..831f8f6 100644
--- a/includes/content/CollaborationListContentHandler.php
+++ b/includes/content/CollaborationListContentHandler.php
@@ -1,7 +1,14 @@
<?php
-// We extend TextContentHandler instead of JsonContentHandler since
-// we do not display this as Json code.
+/**
+ * Content handler for CollaborationListContent.
+ *
+ * We extend TextContentHandler instead of JsonContentHandler since
+ * we do not display this as JSON code except upon request.
+ *
+ * @file
+ */
+
class CollaborationListContentHandler extends TextContentHandler {
const FORMAT_WIKI = 'text/x-collabkit';
@@ -20,7 +27,9 @@
}
/**
- * @param $title Title of page to check
+ * Can this content handler be used on a given page?
+ *
+ * @param Title $title Page to check
* @return bool
*/
public function canBeUsedOn( Title $title ) {
@@ -33,6 +42,10 @@
}
/**
+ * Takes JSON string and creates a new CollaborationListContent object.
+ *
+ * Validation is intentionally not done at this step, as it is done
later.
+ *
* @param string $text
* @param string $format
* @return CollaborationListContent
@@ -45,10 +58,16 @@
$text = FormatJson::encode( $data );
}
$content = new CollaborationListContent( $text );
- // Deliberately not validating at this step; validation is done
later.
return $content;
}
+ /**
+ * Prepares a serialization of the content object.
+ *
+ * @param Content $content
+ * @param string $format
+ * @return string
+ */
public function serializeContent( Content $content, $format = null ) {
if ( $format === self::FORMAT_WIKI ) {
return $content->convertToHumanEditable();
@@ -74,7 +93,10 @@
}
/**
- * @param $username string
+ * Spawns a new "members" list, using the project creator as initial
member.
+ *
+ * @param string $username Username without "User:" prefix
+ * @param string $initialDescription The initial description of the list
* @return CollaborationListContent
*/
public static function makeMemberList( $username, $initialDescription )
{
@@ -130,9 +152,11 @@
}
/**
- * @param $title Title
- * @param $summary string
- * @param $context IContextSource
+ * Posts the newly created "members" list on-wiki.
+ *
+ * @param Title $title
+ * @param string $summary
+ * @param IContextSource $context
* @todo rework this to use a generic CollaborationList editor function
once it exists
*/
public static function postMemberList( Title $title, $summary,
IContextSource $context ) {
diff --git a/modules/ext.CollaborationKit.hubimage.js
b/modules/ext.CollaborationKit.hubimage.js
index ba72513..286fb19 100644
--- a/modules/ext.CollaborationKit.hubimage.js
+++ b/modules/ext.CollaborationKit.hubimage.js
@@ -1,6 +1,10 @@
( function ( $, mw, OO ) {
- // Subclass ProcessDialog.
+ /**
+ * Subclass ProcessDialog.
+ *
+ * @param {Object} config
+ */
function ProcessDialog( config ) {
ProcessDialog.super.call( this, config );
}
@@ -14,8 +18,10 @@
{ label: mw.msg( 'cancel' ), flags: 'safe' }
];
- // Use the initialize() method to add content to the dialog's $body,
- // to initialize widgets, and to set up event handlers.
+ /**
+ * Use the initialize() method to add content to the dialog's $body,
+ * to initialize widgets, and to set up event handlers.
+ */
ProcessDialog.prototype.initialize = function () {
var defaultSearchTerm, nsPrefix;
@@ -46,7 +52,10 @@
this.$body.append( this.content.$element );
};
- // In the event "Select" is pressed
+ /**
+ * In the event "Select" is pressed
+ *
+ */
ProcessDialog.prototype.getActionProcess = function ( action ) {
var dialog, openItUp, windowManager, processDialog,
currentImageFilename, currentImage,
hubimageBrowserButton;
@@ -80,12 +89,18 @@
return ProcessDialog.super.prototype.getActionProcess.call(
this, action );
};
- // Get dialog height.
+ /**
+ * Get dialog height.
+ *
+ * @return {int} Dialog height
+ */
ProcessDialog.prototype.getBodyHeight = function () {
return 600;
};
- // Create and append the window manager.
+ /**
+ * Create and append the window manager.
+ */
openItUp = function () {
windowManager = new OO.ui.WindowManager();
$( 'body' ).append( windowManager.$element );
diff --git a/modules/ext.CollaborationKit.icon.js
b/modules/ext.CollaborationKit.icon.js
index ef8ff99..779b7eb 100644
--- a/modules/ext.CollaborationKit.icon.js
+++ b/modules/ext.CollaborationKit.icon.js
@@ -1,6 +1,10 @@
( function ( $, mw, OO ) {
- // Subclass ProcessDialog.
+ /**
+ * Subclass ProcessDialog.
+ *
+ * @param {Object} config
+ */
function ProcessDialog( config ) {
ProcessDialog.super.call( this, config );
}
@@ -14,8 +18,10 @@
{ label: mw.msg( 'cancel' ), flags: 'safe' }
];
- // Use the initialize() method to add content to the dialog's $body,
- // to initialize widgets, and to set up event handlers.
+ /**
+ * Use the initialize() method to add content to the dialog's $body,
+ * to initialize widgets, and to set up event handlers.
+ */
ProcessDialog.prototype.initialize = function () {
var iconList, radioChoices, className;
@@ -53,7 +59,10 @@
this.$body.append( this.content.$element );
};
- // In the event "Select" is pressed
+ /**
+ * In the event "Select" is pressed
+ *
+ */
ProcessDialog.prototype.getActionProcess = function ( action ) {
var dialog, toAppend, openItUp, windowManager, processDialog,
iconBrowserButton;
@@ -77,12 +86,18 @@
return ProcessDialog.super.prototype.getActionProcess.call(
this, action );
};
- // Get dialog height.
+ /**
+ * Get dialog height.
+ *
+ * @return {int} Dialog height
+ */
ProcessDialog.prototype.getBodyHeight = function () {
return this.content.$element.outerHeight( true );
};
- // Create and append the window manager.
+ /**
+ * Create and append the window manager
+ */
openItUp = function () {
windowManager = new OO.ui.WindowManager();
$( 'body' ).append( windowManager.$element );
diff --git a/modules/ext.CollaborationKit.list.edit.js
b/modules/ext.CollaborationKit.list.edit.js
index e30d948..1d9b7dd 100644
--- a/modules/ext.CollaborationKit.list.edit.js
+++ b/modules/ext.CollaborationKit.list.edit.js
@@ -1,6 +1,12 @@
( function ( $, mw, OO ) {
var deleteItem, getCurrentJson, saveJson, addItem, reorderList,
getListOfTitles, modifyItem, modifyExistingItem, addSelf, curUserIsInList,
getCol;
+ /**
+ * Retrieves ID number of column
+ *
+ * @param {jQuery} $item
+ * @return {int}
+ */
getColId = function ( $item ) {
var $col, id;
@@ -12,6 +18,11 @@
return id;
};
+ /**
+ * Deletes an item from the list
+ *
+ * @param {jQuery} $item
+ */
deleteItem = function ( $item ) {
var cur,
$spinner,
@@ -203,6 +214,12 @@
} );
};
+ /**
+ * Retrieves JSON form of the list content
+ *
+ * @param {int} pageID
+ * @param {function} callback
+ */
getCurrentJson = function ( pageId, callback ) {
var api = new mw.Api();
@@ -240,6 +257,12 @@
);
};
+ /**
+ * Saves the JSON text to a CollaborationListContent page
+ *
+ * @param {Object} params
+ * @param {function} callback
+ */
saveJson = function ( params, callback ) {
var api = new mw.Api();
diff --git a/modules/ext.CollaborationKit.list.ui.js
b/modules/ext.CollaborationKit.list.ui.js
index d743205..5a0fa36 100644
--- a/modules/ext.CollaborationKit.list.ui.js
+++ b/modules/ext.CollaborationKit.list.ui.js
@@ -1,11 +1,18 @@
( function ( $, mw, OO ) {
var LE = require( 'ext.CollaborationKit.list.edit' );
+ /**
+ * Adds a new item to a list
+ *
+ * @param {int} colId The ID number of the column
+ */
addItem = function ( colId ) {
modifyItem( { itemColId: colId } );
};
/**
+ * Opens a window to manage list item modification
+ *
* @param {Object} itemToEdit The name of the title to modify, or false
to add new.
*/
modifyItem = function ( itemToEdit ) {
--
To view, visit https://gerrit.wikimedia.org/r/337375
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I5b39a14bf8e545f167a96dc0341443d85c10d02f
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/CollaborationKit
Gerrit-Branch: master
Gerrit-Owner: Harej <jamesmh...@gmail.com>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
