docs/reference/fidl/language/error-catalog/_INSTRUCTIONS.md

# README

This directory is a catalog of all fidlc errors. Each error has a Markdown file
that describes it with "good" and "bad" example code.

## Adding a new error

Run this script, then edit the TODOs in the new files it creates:

    $FUCHSIA_DIR/tools/fidl/scripts/add_errcat_entry.py {ERROR_NUMBER} \
        --bad={NUMBER_OF_BAD_EXAMPLES} \
        --good={NUMBER_OF_GOOD_EXAMPLES}

### Manually adding a new error

Follow these steps if the script doesn't work:

- Create `//docs/reference/fidl/language/error-catalog/_fi-NNNN.md`, replacing
  the `NNNN` with the new error code.

- Add the new error to the end of `//docs/reference/fidl/language/_files.txt`:

      _fi-NNNN.md

- Add the new error to the end of `//docs/reference/fidl/language/errcat.md`:

      <<error-catalog/_fi-NNNN.md>>

- Add a new entry to the end of `//docs/error/_redirects.yaml`:

      - from: /fuchsia-src/error/fi-NNNN
        to: /fuchsia-src/reference/fidl/language/errcat.md#fi-NNNN

- Create at least one good example in `//tools/fidl/fidlc/tests/fidl/good`.
  If you're creating only one, name it `fi-NNNN.test.fidl`. Otherwise, name
  them `fi-NNNN-a.test.fidl`, `fi-NNNN-b.test.fidl`, etc.

- Create at least one bad example in `//tools/fidl/fidlc/tests/fidl/bad`.
  If you're creating only one, name it `fi-NNNN.test.fidl`. Otherwise, name
  them `fi-NNNN-a.test.fidl`, `fi-NNNN-b.test.fidl`, etc.

- Add a test case to `//tools/fidl/fidlc/tests/errcat_good_tests.cc` using the
  "good" example.

- Add or update an existing test case using the "bad" example. A good way to
  find existing test cases is to grep for the error name. If there are no
  existing test cases, add a new one somewhere in `//tools/fidl/fidlc/tests`.

## Retiring an error

- Delete good and bad examples:

      rm tools/fidl/fidlc/tests/fidl/{good,bad}/fi-NNNN*.test.fidl

- Update `//docs/reference/fidl/language/error-catalog/_fi-NNNN.md`:

      ## fi-NNNN {:#fi-NNNN .hide-from-toc}

      Deprecated: This error code has been retired.

- Change `//tools/fidl/fidlc/src/diagnostics.h` to define the error
  using `RetiredDef` instead of `ErrorDef`. For example:

      -constexpr ErrorDef<10, std::string_view> ErrInvalidIdentifier("invalid identifier '{}'");
      +constexpr RetiredDef<10> ErrInvalidIdentifier;