docs(deprecated): update uses and examples of keyword with attribute

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;
      }