mirror of
https://gerrit.wikimedia.org/r/mediawiki/extensions/DiscussionTools
synced 2024-12-11 16:16:51 +00:00
69e8e948b2
MediaWiki's PHPCS plugin requires documentation comments on all methods, unless those methods are fully typed (all parameters and return value). It turns out that almost all of our methods are fully typed already. Procedure: 1. Find: \*(\s*\*\s*(@param \??[\w\\]+(\|null)? &?\$\w+|@return \??[\w\\]+(\|null)?)\n)+\s*\*/ Replace with: */ This deletes type annotations, except those not representable as PHP type hints such as union types `a|b` or typed arrays `a[]`, or those with documentation beyond type hints, or those on functions with any other annotations. 2. Find: /\*\*/\n\s* Replace with nothing This deletes the remaining comments on methods that had no prose documentation. 3. Undo all changes that PHPCS complains about (those comments were not redundant) 4. Review the diff carefully, these regexps are imprecise :) Change-Id: Ic82e8b23f2996f44951208dbd9cfb4c8e0738dac
105 lines
3.2 KiB
PHP
105 lines
3.2 KiB
PHP
<?php
|
|
|
|
namespace MediaWiki\Extension\DiscussionTools\ThreadItem;
|
|
|
|
use MediaWiki\Extension\DiscussionTools\ImmutableRange;
|
|
use Wikimedia\Assert\Assert;
|
|
use Wikimedia\Parsoid\DOM\Element;
|
|
|
|
class ContentHeadingItem extends ContentThreadItem implements HeadingItem {
|
|
use HeadingItemTrait {
|
|
jsonSerialize as traitJsonSerialize;
|
|
}
|
|
|
|
private bool $placeholderHeading;
|
|
private int $headingLevel;
|
|
private bool $uneditableSection = false;
|
|
|
|
// Placeholder headings must have a level higher than real headings (1-6)
|
|
private const PLACEHOLDER_HEADING_LEVEL = 99;
|
|
|
|
/**
|
|
* @param ImmutableRange $range
|
|
* @param bool|string $transcludedFrom
|
|
* @param ?int $headingLevel Heading level (1-6). Use null for a placeholder heading.
|
|
*/
|
|
public function __construct(
|
|
ImmutableRange $range, $transcludedFrom, ?int $headingLevel
|
|
) {
|
|
parent::__construct( 'heading', 0, $range, $transcludedFrom );
|
|
$this->placeholderHeading = $headingLevel === null;
|
|
$this->headingLevel = $this->placeholderHeading ? static::PLACEHOLDER_HEADING_LEVEL : $headingLevel;
|
|
}
|
|
|
|
/**
|
|
* Get a title based on the hash ID, such that it can be linked to
|
|
*
|
|
* @return string Title
|
|
*/
|
|
public function getLinkableTitle(): string {
|
|
$title = '';
|
|
// If this comment is in 0th section, there's no section title for the edit summary
|
|
if ( !$this->isPlaceholderHeading() ) {
|
|
// <span class="mw-headline" …>, or <hN …> in Parsoid HTML
|
|
$headline = $this->getRange()->startContainer;
|
|
Assert::precondition( $headline instanceof Element, 'HeadingItem refers to an element node' );
|
|
$id = $headline->getAttribute( 'id' ) ?: $headline->getAttribute( 'data-mw-anchor' );
|
|
if ( $id ) {
|
|
// Replace underscores with spaces to undo Sanitizer::escapeIdInternal().
|
|
// This assumes that $wgFragmentMode is [ 'html5', 'legacy' ] or [ 'html5' ],
|
|
// otherwise the escaped IDs are super garbled and can't be unescaped reliably.
|
|
$title = str_replace( '_', ' ', $id );
|
|
}
|
|
// else: Not a real section, probably just HTML markup in wikitext
|
|
}
|
|
return $title;
|
|
}
|
|
|
|
public function isUneditableSection(): bool {
|
|
return $this->uneditableSection;
|
|
}
|
|
|
|
/**
|
|
* @param bool $uneditableSection The heading represents a section that can't be
|
|
* edited on its own.
|
|
*/
|
|
public function setUneditableSection( bool $uneditableSection ): void {
|
|
$this->uneditableSection = $uneditableSection;
|
|
}
|
|
|
|
/**
|
|
* @return int Heading level (1-6)
|
|
*/
|
|
public function getHeadingLevel(): int {
|
|
return $this->headingLevel;
|
|
}
|
|
|
|
/**
|
|
* @param int $headingLevel Heading level (1-6)
|
|
*/
|
|
public function setHeadingLevel( int $headingLevel ): void {
|
|
$this->headingLevel = $headingLevel;
|
|
}
|
|
|
|
public function isPlaceholderHeading(): bool {
|
|
return $this->placeholderHeading;
|
|
}
|
|
|
|
public function setPlaceholderHeading( bool $placeholderHeading ): void {
|
|
$this->placeholderHeading = $placeholderHeading;
|
|
}
|
|
|
|
/**
|
|
* @inheritDoc
|
|
*/
|
|
public function jsonSerialize( bool $deep = false, ?callable $callback = null ): array {
|
|
$data = $this->traitJsonSerialize( $deep, $callback );
|
|
|
|
// When this is false (which is most of the time), omit the key for efficiency
|
|
if ( $this->isUneditableSection() ) {
|
|
$data[ 'uneditableSection' ] = true;
|
|
}
|
|
return $data;
|
|
}
|
|
}
|