Merge pull request #1731 from sarjona/externaldeprecation

[docs] Clarify external funcions deprecation process

Author: junpataleta

docs/apis/subsystems/external/writing-a-service.md

@@ -464,18 +464,44 @@ Edit your `local/groupmanager/version.php` and increase the plugin version. This
 
 ## Deprecation {/* #deprecation */}
 
-External functions deprecation process is slightly different from the standard deprecation. If you are interested in deprecating any of your external functions you should **also** (apart from the applicable points detailed in the [standard deprecation docs](/general/development/policies/deprecation)) create a `FUNCTIONNAME_is_deprecated()` method in your external function class. Return true if the external function is deprecated. This is an example:
+The deprecation process for external functions is different from the [standard deprecation](/general/development/policies/deprecation) process. To deprecate an external function, you must do **both** of the following:
+
+1. Create a `FUNCTIONNAME_is_deprecated()` method in your external function class, returning `true`. The web service framework uses this method to flag the function as deprecated.
+1. Add the `@deprecated` PHPDoc tag, documenting the version it was deprecated in and the MDL issue, so that IDEs show the function as deprecated:
+    - When the whole class is deprecated (for example, a class with a single `execute()` external function), add the tag to the class PHPDoc.
+    - Otherwise, add the tag to each of the deprecated methods (`FUNCTIONNAME_parameters()`, `FUNCTIONNAME()` and `FUNCTIONNAME_returns()`).
 
 ```php
+/**
+ * Create groups.
+ *
+ * @package    local_groupmanager
+ * @copyright  2026 Your Name <you@example.com>
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated since 5.3 MDL-XXXXX
+ */
+class create_groups extends \core_external\external_api {
+    // ...
+
     /**
      * Mark the function as deprecated.
+     *
      * @return bool
      */
-    public static function execute_is_deprecated() {
+    public static function execute_is_deprecated(): bool {
         return true;
     }
+}
 ```
 
+:::danger
+
+Do **not** add the `\core\attribute\deprecated` attribute, nor call `\core\deprecation::emit_deprecation()` or `\core\deprecation::emit_deprecation_if_present()`, in external functions. The `FUNCTIONNAME_is_deprecated()` method is the only mechanism needed to mark them as deprecated at runtime.
+
+:::
+
+The remaining applicable points of the [standard deprecation](/general/development/policies/deprecation) process (such as creating the follow-up issue for the final deprecation and adding an upgrade note) still apply.
+
 ## See also {/* #see-also */}
 
 - [Web services developer documentation](./index.md)

general/development/policies/deprecation/index.md

@@ -99,7 +99,7 @@ debugging('foobar() is deprecated. Please use foobar::blah() instead.', DEBUG_DE
 - Unit tests that call the function should have `assertDebuggingCalled()` added to allow them to continue running.
 - If the deprecated function has been replaced with a new function, ideally the new function should be called from the deprecated function, so that the new functionality is used. This will make maintenance easier moving forward.
 - A `@deprecated` tag should be added to the PHPDoc for the function description so that IDEs describing the function will note that it is deprecated, documenting which version it was deprecated in and the MDL issue associated with it. See the guidelines in [Coding style](../codingstyle/index.md#deprecated-and-todo).
-- If the function is an external function, then an additional deprecation-specific method needs to be created and set to return true. See the [adding a web service to a plugin](/docs/apis/subsystems/external/writing-a-service#deprecation) docs on that process. You should continue to add the `@deprecated since x.x` tag to the docs of all three of the relevant external methods (parameters, main method, returns) to make it clear to IDEs that the function is deprecated.
+- If the function is an external function, the process is different from the one described above. Follow the [external functions deprecation](/docs/apis/subsystems/external/writing-a-service#deprecation) docs instead.
 - There will need to be an issue associated with the initial part of the deprecation. A second issue needs to be created to finish the job. The first issue will be linked to second issue. The second issue needs to be a sub-task of an appropriate [deprecation META](https://moodle.atlassian.net/issues/?jql=%28summary%20~%20%22meta%22%20or%20type%20%3D%20Epic%29%20AND%20summary%20~%20%22together%20deprecated%22%20order%20by%20created&runQuery=true&clear=true).
 
 :::note[Example]

versioned_docs/version-4.5/apis/subsystems/external/writing-a-service.md

@@ -464,18 +464,44 @@ Edit your `local/groupmanager/version.php` and increase the plugin version. This
 
 ## Deprecation {/* #deprecation */}
 
-External functions deprecation process is slightly different from the standard deprecation. If you are interested in deprecating any of your external functions you should **also** (apart from the applicable points detailed in the [standard deprecation docs](/general/development/policies/deprecation)) create a `FUNCTIONNAME_is_deprecated()` method in your external function class. Return true if the external function is deprecated. This is an example:
+The deprecation process for external functions is different from the [standard deprecation](/general/development/policies/deprecation) process. To deprecate an external function, you must do **both** of the following:
+
+1. Create a `FUNCTIONNAME_is_deprecated()` method in your external function class, returning `true`. The web service framework uses this method to flag the function as deprecated.
+1. Add the `@deprecated` PHPDoc tag, documenting the version it was deprecated in and the MDL issue, so that IDEs show the function as deprecated:
+    - When the whole class is deprecated (for example, a class with a single `execute()` external function), add the tag to the class PHPDoc.
+    - Otherwise, add the tag to each of the deprecated methods (`FUNCTIONNAME_parameters()`, `FUNCTIONNAME()` and `FUNCTIONNAME_returns()`).
 
 ```php
+/**
+ * Create groups.
+ *
+ * @package    local_groupmanager
+ * @copyright  2026 Your Name <you@example.com>
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated since 4.5 MDL-XXXXX
+ */
+class create_groups extends \core_external\external_api {
+    // ...
+
     /**
      * Mark the function as deprecated.
+     *
      * @return bool
      */
-    public static function execute_is_deprecated() {
+    public static function execute_is_deprecated(): bool {
         return true;
     }
+}
 ```
 
+:::danger
+
+Do **not** add the `\core\attribute\deprecated` attribute, nor call `\core\deprecation::emit_deprecation()` or `\core\deprecation::emit_deprecation_if_present()`, in external functions. The `FUNCTIONNAME_is_deprecated()` method is the only mechanism needed to mark them as deprecated at runtime.
+
+:::
+
+The remaining applicable points of the [standard deprecation](/general/development/policies/deprecation) process (such as creating the follow-up issue for the final deprecation and adding an upgrade note) still apply.
+
 ## See also {/* #see-also */}
 
 - [Web services developer documentation](./index.md)

versioned_docs/version-5.0/apis/subsystems/external/writing-a-service.md

@@ -464,18 +464,44 @@ Edit your `local/groupmanager/version.php` and increase the plugin version. This
 
 ## Deprecation {/* #deprecation */}
 
-External functions deprecation process is slightly different from the standard deprecation. If you are interested in deprecating any of your external functions you should **also** (apart from the applicable points detailed in the [standard deprecation docs](/general/development/policies/deprecation)) create a `FUNCTIONNAME_is_deprecated()` method in your external function class. Return true if the external function is deprecated. This is an example:
+The deprecation process for external functions is different from the [standard deprecation](/general/development/policies/deprecation) process. To deprecate an external function, you must do **both** of the following:
+
+1. Create a `FUNCTIONNAME_is_deprecated()` method in your external function class, returning `true`. The web service framework uses this method to flag the function as deprecated.
+1. Add the `@deprecated` PHPDoc tag, documenting the version it was deprecated in and the MDL issue, so that IDEs show the function as deprecated:
+    - When the whole class is deprecated (for example, a class with a single `execute()` external function), add the tag to the class PHPDoc.
+    - Otherwise, add the tag to each of the deprecated methods (`FUNCTIONNAME_parameters()`, `FUNCTIONNAME()` and `FUNCTIONNAME_returns()`).
 
 ```php
+/**
+ * Create groups.
+ *
+ * @package    local_groupmanager
+ * @copyright  2026 Your Name <you@example.com>
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated since 5.0 MDL-XXXXX
+ */
+class create_groups extends \core_external\external_api {
+    // ...
+
     /**
      * Mark the function as deprecated.
+     *
      * @return bool
      */
-    public static function execute_is_deprecated() {
+    public static function execute_is_deprecated(): bool {
         return true;
     }
+}
 ```
 
+:::danger
+
+Do **not** add the `\core\attribute\deprecated` attribute, nor call `\core\deprecation::emit_deprecation()` or `\core\deprecation::emit_deprecation_if_present()`, in external functions. The `FUNCTIONNAME_is_deprecated()` method is the only mechanism needed to mark them as deprecated at runtime.
+
+:::
+
+The remaining applicable points of the [standard deprecation](/general/development/policies/deprecation) process (such as creating the follow-up issue for the final deprecation and adding an upgrade note) still apply.
+
 ## See also {/* #see-also */}
 
 - [Web services developer documentation](./index.md)

versioned_docs/version-5.1/apis/subsystems/external/writing-a-service.md

@@ -464,18 +464,44 @@ Edit your `local/groupmanager/version.php` and increase the plugin version. This
 
 ## Deprecation {/* #deprecation */}
 
-External functions deprecation process is slightly different from the standard deprecation. If you are interested in deprecating any of your external functions you should **also** (apart from the applicable points detailed in the [standard deprecation docs](/general/development/policies/deprecation)) create a `FUNCTIONNAME_is_deprecated()` method in your external function class. Return true if the external function is deprecated. This is an example:
+The deprecation process for external functions is different from the [standard deprecation](/general/development/policies/deprecation) process. To deprecate an external function, you must do **both** of the following:
+
+1. Create a `FUNCTIONNAME_is_deprecated()` method in your external function class, returning `true`. The web service framework uses this method to flag the function as deprecated.
+1. Add the `@deprecated` PHPDoc tag, documenting the version it was deprecated in and the MDL issue, so that IDEs show the function as deprecated:
+    - When the whole class is deprecated (for example, a class with a single `execute()` external function), add the tag to the class PHPDoc.
+    - Otherwise, add the tag to each of the deprecated methods (`FUNCTIONNAME_parameters()`, `FUNCTIONNAME()` and `FUNCTIONNAME_returns()`).
 
 ```php
+/**
+ * Create groups.
+ *
+ * @package    local_groupmanager
+ * @copyright  2026 Your Name <you@example.com>
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated since 5.1 MDL-XXXXX
+ */
+class create_groups extends \core_external\external_api {
+    // ...
+
     /**
      * Mark the function as deprecated.
+     *
      * @return bool
      */
-    public static function execute_is_deprecated() {
+    public static function execute_is_deprecated(): bool {
         return true;
     }
+}
 ```
 
+:::danger
+
+Do **not** add the `\core\attribute\deprecated` attribute, nor call `\core\deprecation::emit_deprecation()` or `\core\deprecation::emit_deprecation_if_present()`, in external functions. The `FUNCTIONNAME_is_deprecated()` method is the only mechanism needed to mark them as deprecated at runtime.
+
+:::
+
+The remaining applicable points of the [standard deprecation](/general/development/policies/deprecation) process (such as creating the follow-up issue for the final deprecation and adding an upgrade note) still apply.
+
 ## See also {/* #see-also */}
 
 - [Web services developer documentation](./index.md)

versioned_docs/version-5.2/apis/subsystems/external/writing-a-service.md

@@ -464,18 +464,44 @@ Edit your `local/groupmanager/version.php` and increase the plugin version. This
 
 ## Deprecation {/* #deprecation */}
 
-External functions deprecation process is slightly different from the standard deprecation. If you are interested in deprecating any of your external functions you should **also** (apart from the applicable points detailed in the [standard deprecation docs](/general/development/policies/deprecation)) create a `FUNCTIONNAME_is_deprecated()` method in your external function class. Return true if the external function is deprecated. This is an example:
+The deprecation process for external functions is different from the [standard deprecation](/general/development/policies/deprecation) process. To deprecate an external function, you must do **both** of the following:
+
+1. Create a `FUNCTIONNAME_is_deprecated()` method in your external function class, returning `true`. The web service framework uses this method to flag the function as deprecated.
+1. Add the `@deprecated` PHPDoc tag, documenting the version it was deprecated in and the MDL issue, so that IDEs show the function as deprecated:
+    - When the whole class is deprecated (for example, a class with a single `execute()` external function), add the tag to the class PHPDoc.
+    - Otherwise, add the tag to each of the deprecated methods (`FUNCTIONNAME_parameters()`, `FUNCTIONNAME()` and `FUNCTIONNAME_returns()`).
 
 ```php
+/**
+ * Create groups.
+ *
+ * @package    local_groupmanager
+ * @copyright  2026 Your Name <you@example.com>
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated since 5.2 MDL-XXXXX
+ */
+class create_groups extends \core_external\external_api {
+    // ...
+
     /**
      * Mark the function as deprecated.
+     *
      * @return bool
      */
-    public static function execute_is_deprecated() {
+    public static function execute_is_deprecated(): bool {
         return true;
     }
+}
 ```
 
+:::danger
+
+Do **not** add the `\core\attribute\deprecated` attribute, nor call `\core\deprecation::emit_deprecation()` or `\core\deprecation::emit_deprecation_if_present()`, in external functions. The `FUNCTIONNAME_is_deprecated()` method is the only mechanism needed to mark them as deprecated at runtime.
+
+:::
+
+The remaining applicable points of the [standard deprecation](/general/development/policies/deprecation) process (such as creating the follow-up issue for the final deprecation and adding an upgrade note) still apply.
+
 ## See also {/* #see-also */}
 
 - [Web services developer documentation](./index.md)