Merge "Documentation fixes"

includes/CommentModifier.php

@@ -87,7 +87,7 @@ class CommentModifier {
 	 * Given a comment and a reply link, add the reply link to its document's DOM tree, at the end of
 	 * the comment.
 	 *
-	 * @param CommentItem $comment Comment data returned by parser#groupThreads
+	 * @param CommentItem $comment Comment item
 	 * @param DOMElement $linkNode Reply link
 	 */
 	public static function addReplyLink( CommentItem $comment, DOMElement $linkNode ) : void {
@@ -123,7 +123,7 @@ class CommentModifier {
 	 * The DOM tree is suitably rearranged to ensure correct indentation level of the reply (wrapper
 	 * nodes are added, and other nodes may be moved around).
 	 *
-	 * @param CommentItem $comment Comment data returned by parser#groupThreads
+	 * @param CommentItem $comment Comment item
 	 * @return DOMElement
 	 */
 	public static function addListItem( CommentItem $comment ) : DOMElement {

includes/CommentParser.php

@@ -939,7 +939,7 @@ class CommentParser {
 	/**
 	 * Get the list of authors involved in a comment and its replies.
 	 *
-	 * @param HeadingItem $heading Heading object, as returned by #groupThreads
+	 * @param HeadingItem $heading Heading item
 	 * @return string[] Author usernames
 	 */
 	public function getAuthors( HeadingItem $heading ) : array {
@@ -962,7 +962,7 @@ class CommentParser {
 	/**
 	 * Get the name of the page from which this comment is transcluded (if any).
 	 *
-	 * @param CommentItem $comment Comment object, as returned by #groupThreads
+	 * @param CommentItem $comment Comment item
 	 * @return string|bool `false` if this comment is not transcluded. A string if it's transcluded
 	 *   from a single page (the page title, in text form with spaces). `true` if it's transcluded, but
 	 *   we can't determine the source.

includes/CommentUtils.php

@@ -117,7 +117,7 @@ class CommentUtils {
 	/**
 	 * Get a node (if any) that contains the given comment, and nothing else.
 	 *
-	 * @param CommentItem $comment Comment data returned by parser#groupThreads
+	 * @param CommentItem $comment Comment item
 	 * @return DOMElement|null
 	 */
 	public static function getFullyCoveredWrapper( CommentItem $comment ) : ?DOMElement {

modules/modifier.js

@@ -59,7 +59,7 @@ function sanitizeWikitextLinebreaks( wikitext ) {
  * Given a comment and a reply link, add the reply link to its document's DOM tree, at the end of
  * the comment.
  *
- * @param {CommentItem} comment Comment data returned by parser#groupThreads
+ * @param {CommentItem} comment Comment item
  * @param {HTMLElement} linkNode Reply link
  */
 function addReplyLink( comment, linkNode ) {
@@ -90,7 +90,7 @@ function addReplyLink( comment, linkNode ) {
  * The DOM tree is suitably rearranged to ensure correct indentation level of the reply (wrapper
  * nodes are added, and other nodes may be moved around).
  *
- * @param {CommentItem} comment Comment data returned by parser#groupThreads
+ * @param {CommentItem} comment Comment item
  * @return {HTMLElement}
  */
 function addListItem( comment ) {

modules/parser.js

@@ -915,7 +915,7 @@ function groupThreads( comments ) {
 /**
  * Get the list of authors involved in a comment and its replies.
  *
- * @param {HeadingItem} heading Comment object, as returned by #groupThreads
+ * @param {HeadingItem} heading Heading item
  * @return {string[]} Author usernames
  */
 function getAuthors( heading ) {
@@ -934,7 +934,7 @@ function getAuthors( heading ) {
 /**
  * Get the name of the page from which this comment is transcluded (if any).
  *
- * @param {CommentItem} comment Comment object, as returned by #groupThreads
+ * @param {CommentItem} comment Comment item
  * @return {string|boolean} `false` if this comment is not transcluded. A string if it's transcluded
  *   from a single page (the page title, in text form with spaces). `true` if it's transcluded, but
  *   we can't determine the source.

modules/utils.js

@@ -1,6 +1,10 @@
 'use strict';
 /* global $:off */
 
+/**
+ * @external CommentItem
+ */
+
 /**
  * Return a native Range object corresponding to our comment's range.
  *
@@ -117,7 +121,7 @@ function htmlTrim( str ) {
 /**
  * Get a node (if any) that contains the given comment, and nothing else.
  *
- * @param {Object} comment Comment data returned by parser#groupThreads
+ * @param {CommentItem} comment Comment item
  * @return {HTMLElement|null}
  */
 function getFullyCoveredWrapper( comment ) {

tests/phpunit/CommentParserTest.php

@@ -270,8 +270,7 @@ class CommentParserTest extends CommentTestCase {
 
 	/**
 	 * @dataProvider provideTranscludedFrom
-	 * @covers ::getComments
-	 * @covers ::groupThreads
+	 * @covers ::getTranscludedFrom
 	 * @covers \MediaWiki\Extension\DiscussionTools\CommentUtils::unwrapParsoidSections
 	 */
 	public function testGetTranscludedFrom(

tests/qunit/testUtils.js

@@ -1,3 +1,7 @@
+/**
+ * @external CommentItem
+ */
+
 var
 	utils = require( 'ext.discussionTools.init' ).utils;
 
@@ -76,7 +80,7 @@ function getOffsetPath( ancestor, node, nodeOffset ) {
 /**
  * Massage comment data to make it serializable as JSON.
  *
- * @param {Object} parent Comment returned by parser#groupThreads; modified in-place
+ * @param {CommentItem} parent Comment item; modified in-place
  * @param {Node} root Ancestor node of all comments
  */
 module.exports.serializeComments = function ( parent, root ) {