From ca49ffcf07b38a51b9231507249bd6a97fde7ccc Mon Sep 17 00:00:00 2001 From: arezaii Date: Thu, 16 Mar 2023 14:51:30 -0600 Subject: [PATCH] docs(deprecated): update uses and examples of keyword with attribute Signed-off-by: arezaii --- .../developer/bestPractices/Deprecation.rst | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/rst/developer/bestPractices/Deprecation.rst b/doc/rst/developer/bestPractices/Deprecation.rst index 8c987c14468..899e316a26e 100644 --- a/doc/rst/developer/bestPractices/Deprecation.rst +++ b/doc/rst/developer/bestPractices/Deprecation.rst @@ -21,18 +21,18 @@ The deprecation message uses the following format: ``foo is deprecated - please use bar`` For compile-time messaging you can use ``compilerWarning()`` to do this, but -when deprecating symbols the ``deprecated`` keyword often works better because +when deprecating symbols the ``@deprecated`` attribute often works better because it can be applied to any symbol in a uniform way. Look in the test/deprecated and test/deprecated-keyword directories for many examples. Note that the -``deprecated`` keyword itself is likely to be replaced by different syntax in +``@deprecated`` attribute itself is likely to be replaced by different syntax in the future, though this may not affect its use in practice since deprecations typically only last for one release anyway. -Currently, the ``deprecated`` keyword optionally takes a string literal, which -is used for the deprecated symbol's documentation and compiler warning message. -If there is also a documentation comment applied to the symbol that comment -will take precedence when producing documentation. When we produce a compiler -warning we filter it to remove any inline markup. +Currently, the ``@deprecated`` attribute optionally takes a string literal, +which is used for the deprecated symbol's documentation and compiler warning +message. If there is also a documentation comment applied to the symbol that +comment will take precedence when producing documentation. When we produce a +compiler warning we filter it to remove any inline markup. This means if your deprecation message points to the preferred feature using syntax like this: ``foo is deprecated - please use :proc:`bar```, then in the @@ -57,7 +57,7 @@ For example: .. note:: - This step is not necessary when using the ``deprecated`` keyword to + This step is not necessary when using the ``@deprecated`` attribute to generate the documentation. 3. Search for error messages that refer to the deprecated feature. @@ -86,9 +86,9 @@ Changing A Function's Return Type When nothing about a function except its return type needs to change, it can be tricky for a user to opt in to the new behavior. -.. code-block:: chapel +.. code-block:: text - deprecated "foo returning 'int' is deprecated" + @deprecated("foo returning 'int' is deprecated") proc foo(): int { ... } // As written, this replacement would conflict with the original, how can a @@ -98,14 +98,14 @@ be tricky for a user to opt in to the new behavior. In this situation, we recommend adding a ``config param`` and a ``where`` clause that responds to it to the deprecated function and its replacement: -.. code-block:: chapel +.. code-block:: text // The default state should result in the deprecated behavior, so users can // adjust their code at their leisure config param fooReturnsBool = false; // The deprecation message should alert the user to the new flag - deprecated "foo returning 'int' is deprecated, please compile with '-sfooReturnsBool=true' to get the new return type" + @deprecated("foo returning 'int' is deprecated, please compile with '-sfooReturnsBool=true' to get the new return type") proc foo(): int where !fooReturnsBool { ... } // The new function should also use a 'where' clause to opt in to the new @@ -115,9 +115,9 @@ that responds to it to the deprecated function and its replacement: When the deprecated function is removed, the flag should also be deprecated (and removed from the new function to avoid generating noise for the user): -.. code-block:: chapel +.. code-block:: text - deprecated "'fooReturnsBool' is deprecated and no longer has an effect" + @deprecated("'fooReturnsBool' is deprecated and no longer has an effect") config param fooReturnsBool = false; // The old version has been removed, and the flag is no longer needed, so @@ -136,9 +136,9 @@ When only the name of a function argument needs to change and not its type, a new overload will encounter conflicts when a user relies solely on positional ordering: -.. code-block:: chapel +.. code-block:: text - deprecated "argument name 'a' is deprecated, use 'b' instead" + @deprecated("argument name 'a' is deprecated, use 'b' instead") proc foo(a: int) { ... } proc foo(b: int) { ... } @@ -159,10 +159,10 @@ resort"`` - this will avoid conflicts in the positional ordering case while still keeping the old argument name available to generate the deprecation warning: -.. code-block:: chapel +.. code-block:: text pragma "last resort" - deprecated "argument name 'a' is deprecated, use 'b' instead" + @deprecated("argument name 'a' is deprecated, use 'b' instead") proc foo(a: int) { foo(a); // Call function with new argument name } @@ -240,7 +240,7 @@ support for opting in to maintaining the default initializer (which is planned but not currently implemented), this will also require the addition of an equivalent replacement for the default initializer, which is a burden. -.. code-block:: chapel +.. code-block:: text record Foo { var newName: int; @@ -250,7 +250,7 @@ equivalent replacement for the default initializer, which is a burden. } pragma "last resort" - deprecated "'new Foo(oldName=val)' is deprecated, please use 'new Foo(newName=val)' or 'new Foo(val)' instead" + @deprecated("'new Foo(oldName=val)' is deprecated, please use 'new Foo(newName=val)' or 'new Foo(val)' instead") proc init(oldName: int) { this.newName = oldName; }