From d64cbc17e9b5178dfd7cb4b98182d6449704f90f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartosz=20Dziewo=C5=84ski?= <matma.rex@gmail.com>
Date: Wed, 24 Aug 2022 22:41:57 +0200
Subject: [PATCH] docs: Clarify that functions returning namespace names
 include underscores (not spaces)

Bug: T316092
Change-Id: I380e529590033e5d34adc37d21e8607feb4fab19
---
 includes/Title.php                     | 6 +++---
 includes/language/Language.php         | 6 ++++--
 includes/title/MediaWikiTitleCodec.php | 2 +-
 includes/title/TitleFormatter.php      | 2 +-
 4 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/includes/Title.php b/includes/Title.php
index 821962cb405..5e0b77d0b48 100644
--- a/includes/Title.php
+++ b/includes/Title.php
@@ -1155,7 +1155,7 @@ class Title implements LinkTarget, PageIdentity, IDBAccessObject {
 	/**
 	 * Get the namespace text
 	 *
-	 * @return string|false Namespace text
+	 * @return string|false Namespace name with underscores (not spaces), e.g. 'User_talk'
 	 */
 	public function getNsText() {
 		if ( $this->isExternal() ) {
@@ -1185,7 +1185,7 @@ class Title implements LinkTarget, PageIdentity, IDBAccessObject {
 	/**
 	 * Get the namespace text of the subject (rather than talk) page
 	 *
-	 * @return string Namespace text
+	 * @return string Namespace name with underscores (not spaces)
 	 */
 	public function getSubjectNsText() {
 		$services = MediaWikiServices::getInstance();
@@ -1196,7 +1196,7 @@ class Title implements LinkTarget, PageIdentity, IDBAccessObject {
 	/**
 	 * Get the namespace text of the talk page
 	 *
-	 * @return string Namespace text
+	 * @return string Namespace name with underscores (not spaces)
 	 */
 	public function getTalkNsText() {
 		$services = MediaWikiServices::getInstance();
diff --git a/includes/language/Language.php b/includes/language/Language.php
index ff9e29402a7..e19acc65a1e 100644
--- a/includes/language/Language.php
+++ b/includes/language/Language.php
@@ -595,9 +595,11 @@ class Language {
 	/**
 	 * Get a namespace value by key
 	 *
+	 * Namespace name uses underscores (not spaces), e.g. 'MediaWiki_talk'.
+	 *
 	 * <code>
-	 * $mw_ns = $lang->getNsText( NS_MEDIAWIKI );
-	 * echo $mw_ns; // prints 'MediaWiki'
+	 * $mw_ns = $lang->getNsText( NS_MEDIAWIKI_TALK );
+	 * echo $mw_ns; // prints 'MediaWiki_talk'
 	 * </code>
 	 *
 	 * @param int $index The array key of the namespace to return
diff --git a/includes/title/MediaWikiTitleCodec.php b/includes/title/MediaWikiTitleCodec.php
index 5d165437508..5b5c8217032 100644
--- a/includes/title/MediaWikiTitleCodec.php
+++ b/includes/title/MediaWikiTitleCodec.php
@@ -113,7 +113,7 @@ class MediaWikiTitleCodec implements TitleFormatter, TitleParser {
 	 * @param string $text
 	 *
 	 * @throws InvalidArgumentException If the namespace is invalid
-	 * @return string Namespace name with underscores (not spaces)
+	 * @return string Namespace name with underscores (not spaces), e.g. 'User_talk'
 	 */
 	public function getNamespaceName( $namespace, $text ) {
 		if ( $this->language->needsGenderDistinction() &&
diff --git a/includes/title/TitleFormatter.php b/includes/title/TitleFormatter.php
index 3162cbae8c8..50b7115f2be 100644
--- a/includes/title/TitleFormatter.php
+++ b/includes/title/TitleFormatter.php
@@ -97,7 +97,7 @@ interface TitleFormatter {
 	 * @param string $text
 	 *
 	 * @throws InvalidArgumentException
-	 * @return string
+	 * @return string Namespace name with underscores (not spaces), e.g. 'User_talk'
 	 */
 	public function getNamespaceName( $namespace, $text );
 }