Improve custom folding and grouping

PHPStorm can use custom folding regions defined in either the
VisualStudio style or the NetBeans style. The VisualStudio style is more
pleasing to the eye and also works as a vim foldmarker. So get rid of
the previous vim foldmarkers, and use region/endregion.

region/endregion need to be in a single-line comment which is not a doc
comment, and the rest of the comment is used as a region heading (by
both PHPStorm and vim). So to retain Doxygen @name tags, it is
necessary to repeat the section heading, once in a @name and once in a
region. Establish a standard style for this, with a divider and three
spaces before the heading, to better set off the heading name in plain
text.

Besides being the previous vim foldmarker, @{ is also a Doxygen
grouping command. However, almost all prior usages of @{ ... @} in this
sense were broken for one reason or another. It's necessary for the @{
to be in a doc comment, and DISTRIBUTE_GROUP_DOC doesn't work if any of
the individual members in the group are separately documented.

@name alone is sufficient to create a Doxygen section when the sections
are adjacent, but if there is ungrouped content after the section, it
is necessary to use @{ ... @} to avoid having the Doxygen group run on.
So I retained, fixed or added @{ ... @} in certain cases.

I wasn't able to test the changes to the trait documentation in Doxygen
since trait syntax is not recognised and the output is badly broken.

Change-Id: I7d819fdb376c861f40bfc01aed74cd3706141b20

1 files changed, 40 insertions, 47 deletions

diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index 0a807eb83fc2..ef0754f2c875 100644
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -60,11 +60,10 @@ abstract class ApiBase extends ContextSource {
 	private $hookRunner;
 
 	/**
-	 * @name Old constants for ::getAllowedParams() arrays
+	 * @name   Old constants for ::getAllowedParams() arrays
 	 * @deprecated since 1.35, use the equivalent ParamValidator or TypeDef constants instead.
 	 * @{
 	 */
-
 	public const PARAM_DFLT = ParamValidator::PARAM_DEFAULT;
 	public const PARAM_ISMULTI = ParamValidator::PARAM_ISMULTI;
 	public const PARAM_TYPE = ParamValidator::PARAM_TYPE;
@@ -84,6 +83,7 @@ abstract class ApiBase extends ContextSource {
 	public const PARAM_ISMULTI_LIMIT2 = ParamValidator::PARAM_ISMULTI_LIMIT2;
 	public const PARAM_MAX_BYTES = StringDef::PARAM_MAX_BYTES;
 	public const PARAM_MAX_CHARS = StringDef::PARAM_MAX_CHARS;
+	/** @} */
 
 	/**
 	 * (boolean) Inverse of IntegerDef::PARAM_IGNORE_RANGE
@@ -91,12 +91,8 @@ abstract class ApiBase extends ContextSource {
 	 */
 	public const PARAM_RANGE_ENFORCE = 'api-param-range-enforce';
 
-	/** @} */
-
-	/**
-	 * @name API-specific constants for ::getAllowedParams() arrays
-	 * @{
-	 */
+	// region   API-specific constants for ::getAllowedParams() arrays
+	/** @name   API-specific constants for ::getAllowedParams() arrays */
 
 	/**
 	 * (string|array|Message) Specify an alternative i18n documentation message
@@ -156,7 +152,7 @@ abstract class ApiBase extends ContextSource {
 	 */
 	public const PARAM_TEMPLATE_VARS = 'param-template-vars';
 
-	/** @} */
+	// endregion -- end of API-specific constants for ::getAllowedParams() arrays
 
 	public const ALL_DEFAULT_STRING = '*';
 
@@ -219,10 +215,9 @@ abstract class ApiBase extends ContextSource {
 		}
 	}
 
-	/************************************************************************//**
-	 * @name   Methods to implement
-	 * @{
-	 */
+	/***************************************************************************/
+	// region   Methods to implement
+	/** @name   Methods to implement */
 
 	/**
 	 * Evaluates the parameters, performs the requested query, and sets up
@@ -429,12 +424,11 @@ abstract class ApiBase extends ContextSource {
 		return null;
 	}
 
-	/** @} */
+	// endregion -- end of methods to implement
 
-	/************************************************************************//**
-	 * @name   Data access methods
-	 * @{
-	 */
+	/***************************************************************************/
+	// region   Data access methods
+	/** @name   Data access methods */
 
 	/**
 	 * Get the name of the module being executed by this instance
@@ -662,12 +656,11 @@ abstract class ApiBase extends ContextSource {
 		return $this->hookRunner;
 	}
 
-	/** @} */
+	// endregion -- end of data access methods
 
-	/************************************************************************//**
-	 * @name   Parameter handling
-	 * @{
-	 */
+	/***************************************************************************/
+	// region   Parameter handling
+	/** @name   Parameter handling */
 
 	/**
 	 * Indicate if the module supports dynamically-determined parameters that
@@ -1113,12 +1106,11 @@ abstract class ApiBase extends ContextSource {
 		return false;
 	}
 
-	/** @} */
+	// endregion -- end of parameter handling
 
-	/************************************************************************//**
-	 * @name   Utility methods
-	 * @{
-	 */
+	/***************************************************************************/
+	// region   Utility methods
+	/** @name   Utility methods */
 
 	/**
 	 * Gets the user for whom to get the watchlist
@@ -1273,12 +1265,11 @@ abstract class ApiBase extends ContextSource {
 		} );
 	}
 
-	/** @} */
+	// endregion -- end of utility methods
 
-	/************************************************************************//**
-	 * @name   Warning and error reporting
-	 * @{
-	 */
+	/***************************************************************************/
+	// region   Warning and error reporting
+	/** @name   Warning and error reporting */
 
 	/**
 	 * Add a warning for this module.
@@ -1607,12 +1598,11 @@ abstract class ApiBase extends ContextSource {
 		wfDebugLog( 'api-feature-usage', $s, 'private', $ctx );
 	}
 
-	/** @} */
+	// endregion -- end of warning and error reporting
 
-	/************************************************************************//**
-	 * @name   Help message generation
-	 * @{
-	 */
+	/***************************************************************************/
+	// region   Help message generation
+	/** @name   Help message generation */
 
 	/**
 	 * Return the summary message.
@@ -1993,12 +1983,11 @@ abstract class ApiBase extends ContextSource {
 	public function modifyHelp( array &$help, array $options, array &$tocData ) {
 	}
 
-	/** @} */
+	// endregion -- end of help message generation
 
-	/************************************************************************//**
-	 * @name   Deprecated methods
-	 * @{
-	 */
+	/***************************************************************************/
+	// region   Deprecated methods
+	/** @name   Deprecated methods */
 
 	/**
 	 * Split a multi-valued parameter string, like explode()
@@ -2155,11 +2144,15 @@ abstract class ApiBase extends ContextSource {
 		);
 	}
 
-	/** @} */
+	// endregion -- end of deprecated methods
 
 }
 
-/**
- * For really cool vim folding this needs to be at the end:
- * vim: foldmarker=@{,@} foldmethod=marker
+/*
+ * This file uses VisualStudio style region/endregion fold markers which are
+ * recognised by PHPStorm. If modelines are enabled, the following editor
+ * configuration will also enable folding in vim, if it is in the last 5 lines
+ * of the file. We also use "@name" which creates sections in Doxygen.
+ *
+ * vim: foldmarker=//\ region,//\ endregion foldmethod=marker
  */