[fidlc] Implement @available argument 'renamed'

This implements the @available argument 'renamed' from the design
document "FIDL versioning: Renaming".

The `renamed` argument can only be used on members, not declarations. It
must be used together with either `replaced` or `removed`. For example,
here is how you rename a table field:

    type Foo = table {
        @available(replaced=2, renamed="good_name")
        1: bad_name string;
        @available(added=2)
        1: good_name string;
    };

Here is how you remove a table field and use a different name for it
post-removal, e.g. when targeting multiple versions {1,2}:

    type Foo = table {
        @available(removed=2, renamed="deprecated_name")
        1: name string;
    };

In both cases the original name is free to be reused.

A follow-up will add ordinal validation (https://fxbug.dev/335716034).
This will make the system much more useful since the compiler will
enforce using the correct removed/replaced/renamed combination.

Test: fx test fidlc-test
Bug: 42085274
Change-Id: Ibcf4dff225776a6ec604fa9a169f1aef52f36631
Reviewed-on: https://fuchsia-review.googlesource.com/c/fuchsia/+/1042482
Commit-Queue: Mitchell Kember <mkember@google.com>
API-Review: Ian McKellar <ianloic@google.com>
Reviewed-by: Ian McKellar <ianloic@google.com>

Author: Mitchell Kember

docs/error/_redirects.yaml

@@ -422,3 +422,13 @@ redirects:
   to: /fuchsia-src/reference/fidl/language/errcat.md#fi-0209
 - from: /fuchsia-src/error/fi-0210
   to: /fuchsia-src/reference/fidl/language/errcat.md#fi-0210
+- from: /fuchsia-src/error/fi-0211
+  to: /fuchsia-src/reference/fidl/language/errcat.md#fi-0211
+- from: /fuchsia-src/error/fi-0212
+  to: /fuchsia-src/reference/fidl/language/errcat.md#fi-0212
+- from: /fuchsia-src/error/fi-0213
+  to: /fuchsia-src/reference/fidl/language/errcat.md#fi-0213
+- from: /fuchsia-src/error/fi-0214
+  to: /fuchsia-src/reference/fidl/language/errcat.md#fi-0214
+- from: /fuchsia-src/error/fi-0215
+  to: /fuchsia-src/reference/fidl/language/errcat.md#fi-0215

docs/reference/fidl/language/errcat.md

@@ -418,4 +418,14 @@ This document lists all errors emitted by the [FIDL compiler][docs-fidlc],
 
 <<error-catalog/_fi-0210.md>>
 
+<<error-catalog/_fi-0211.md>>
+
+<<error-catalog/_fi-0212.md>>
+
+<<error-catalog/_fi-0213.md>>
+
+<<error-catalog/_fi-0214.md>>
+
+<<error-catalog/_fi-0215.md>>
+
 [docs-fidlc]: ../language/fidlc.md

docs/reference/fidl/language/error-catalog/_fi-0205.md

@@ -1,36 +1,44 @@
-## fi-0205: Removed element must not have a replacement {:#fi-0205}
+## fi-0205: Invalid `@available(removed=N)` {:#fi-0205}
 
-When an element is marked `@available(removed=N)`, it indicates that the element
-can no longer be used at version `N`. It should not merely be replaced by a new
-definition marked `@available(added=N)`:
+When an element is marked `@available(removed=N)`, it means the element can no
+longer be used at version `N`. You cannot reuse its name:
 
 {% include "docs/reference/fidl/language/error-catalog/label/_bad.md" %}
 
 ```fidl
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/bad/fi-0205.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
 ```
 
-If the replacement is intentional, make it explicit by using the `replaced`
-argument instead of the `removed` argument:
+If you want to replace the element with a new definition (same API and ABI), use
+the `replaced` argument instead of the `removed` argument:
 
 {% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
 
 ```fidl
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0205-a.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
 ```
 
-If the replacement is unintentional, remove or rename the other element:
+If you want to remove the element and define a new, unrelated element (different
+API and ABI), choose a different name for the new element:
 
 {% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
 
 ```fidl
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0205-b.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
 ```
 
-The `removed` and `replaced` arguments both have the same effect on the
-generated bindings, but they represent different points in API lifecycle. The
-`removed` argument indicates the end of an API, while the `replaced` argument
-indicates a transition to a new definition.
+If you really want to reuse the name (same API, different ABI), use the
+`renamed` argument to rename the old element post-removal, freeing up its
+original name:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0205-c.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+Notice that in this case you must use `@selector` to ensure the new method has a
+different ABI.
 
 See [FIDL versioning][fidl-versioning] to learn more about versioning.
 

docs/reference/fidl/language/error-catalog/_fi-0206.md

@@ -1,8 +1,8 @@
-## fi-0206: Replaced element has no replacement {:#fi-0206}
+## fi-0206: Invalid `@available(replaced=N)` {:#fi-0206}
 
-When an element is marked `@available(replaced=N)`, it indicates that the
-element is replaced by a new definition marked `@available(added=N)`. The FIDL
-compiler will report an error if it cannot find such a definition:
+When an element is marked `@available(replaced=N)`, it means the element is
+replaced by a new definition marked `@available(added=N)`. The FIDL compiler
+will report an error if it cannot find such a definition:
 
 {% include "docs/reference/fidl/language/error-catalog/label/_bad.md" %}
 
@@ -27,11 +27,6 @@ If you intended to replace the element, add a replacement definition:
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0206-b.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
 ```
 
-The `removed` and `replaced` arguments both have the same effect on the
-generated bindings, but they represent different points in API lifecycle. The
-`removed` argument indicates the end of an API, while the `replaced` argument
-indicates a transition to a new definition.
-
 See [FIDL versioning][fidl-versioning] to learn more about versioning.
 
 [fidl-versioning]: /docs/reference/fidl/language/versioning.md

docs/reference/fidl/language/error-catalog/_fi-0211.md

@@ -0,0 +1,33 @@
+## fi-0211: Element cannot be renamed {:#fi-0211}
+
+The `@available` attribute's `renamed` argument can only be used on members of
+declarations, not on declarations themselves:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_bad.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/bad/fi-0211.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+Instead of renaming a declaration, remove the old one and add a new one:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0211.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+Renaming is only supported on members because the FIDL compiler can compare
+their ABI identity (e.g. table ordinal) to ensure it is done correctly.
+
+The `renamed` argument is also not allowed on the following elements either:
+
+* `library`: You can't rename a library from within because the FIDL toolchain
+  assumes each library has a single name. Instead, you should create a new
+  library with the desired name and migrate users to it.
+* `compose`: You can't rename a protocol composition because compositions are
+  not named to begin with.
+
+See [FIDL versioning][fidl-versioning] to learn more about versioning.
+
+[fidl-versioning]: /docs/reference/fidl/language/versioning.md

docs/reference/fidl/language/error-catalog/_fi-0212.md

@@ -0,0 +1,39 @@
+## fi-0212: Renamed without replaced or removed {:#fi-0212}
+
+The `@available` argument `renamed` is not allowed on its own. It must be used
+together with the `replaced` or `removed` argument:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_bad.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/bad/fi-0212.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+If you just want to rename the element at version `N`, use `replaced=N` and
+define a replacement with the new name marked `added=N`:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0212-a.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+In this case, the replacement method must override `@selector` for ABI
+compatibility.
+
+Alternatively, if you want to remove the element at version `N` and refer to it
+by a different name after its removal, use `removed=N`:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0212-b.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+In this case, the new name will only be used when targeting multiple versions
+(e.g. `--available test:1,2`) since that is the only way to include the element
+while also targeting a version past its removal.
+
+See [FIDL versioning][fidl-versioning] to learn more about versioning.
+
+[fidl-versioning]: /docs/reference/fidl/language/versioning.md

docs/reference/fidl/language/error-catalog/_fi-0213.md

@@ -0,0 +1,30 @@
+## fi-0213: Renamed to same name {:#fi-0213}
+
+When renaming an element with the `@available` argument `renamed`, the new name
+cannot be the same as the element's original name:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_bad.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/bad/fi-0213.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+To fix the error, remove the `renamed` argument:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0213-a.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+Alternatively, keep the `renamed` argument but choose a different name:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0213-b.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+See [FIDL versioning][fidl-versioning] to learn more about versioning.
+
+[fidl-versioning]: /docs/reference/fidl/language/versioning.md

docs/reference/fidl/language/error-catalog/_fi-0214.md

@@ -0,0 +1,39 @@
+## fi-0214: Invalid `@available(removed=N, renamed="NewName")` {:#fi-0214}
+
+This is like [fi-0205: Invalid `@available(removed=N)`](#fi-0205), but for when
+the `renamed` argument is involved.
+
+When an element is marked `@available(removed=N, renamed="NewName")`, it means
+the element can no longer be used at version `N`, and is renamed to "NewName"
+post-removal. You cannot use "NewName" for something else:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_bad.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/bad/fi-0214.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+If you want to rename the element while keeping its ABI, use the `replaced`
+argument instead of the `removed` argument:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0214-a.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+Notice that in this case you must use `@selector` to ensure the renamed method
+has the same ABI.
+
+If you want the new element to have a different ABI, then keep `removed` and
+ensure that the `renamed` argument and the new element use different names:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0214-b.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+See [FIDL versioning][fidl-versioning] to learn more about versioning.
+
+[fidl-versioning]: /docs/reference/fidl/language/versioning.md

docs/reference/fidl/language/error-catalog/_fi-0215.md

@@ -0,0 +1,30 @@
+## fi-0215: Invalid `@available(replaced=N, renamed="NewName")` {:#fi-0215}
+
+This is like [fi-0206: Invalid `@available(replaced=N)`](#fi-0206), but for when
+the `renamed` argument is involved.
+
+When an element is marked `@available(replaced=N, renamed="NewName")`, it means
+the element is replaced by a new definition named "NewName" and marked with
+`@available(added=N)`. The FIDL compiler will report an error if it cannot find
+such a definition:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_bad.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/bad/fi-0215.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+To fix the error, define an element with the new name:
+
+{% include "docs/reference/fidl/language/error-catalog/label/_good.md" %}
+
+```fidl
+{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0215.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
+```
+
+Notice that you must use `@selector` to ensure the renamed method has the same
+ABI.
+
+See [FIDL versioning][fidl-versioning] to learn more about versioning.
+
+[fidl-versioning]: /docs/reference/fidl/language/versioning.md

docs/reference/fidl/language/error-catalog/_files.txt

@@ -205,3 +205,8 @@ _fi-0207.md
 _fi-0208.md
 _fi-0209.md
 _fi-0210.md
+_fi-0211.md
+_fi-0212.md
+_fi-0213.md
+_fi-0214.md
+_fi-0215.md