Doc comments are never allowed to be free-floating, like regular comments:
{% include “docs/reference/fidl/language/error-catalog/label/_bad.md” %}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/bad/fi-0028.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
Doc comments must directly precede FIDL declarations in all circumstances:
{% include “docs/reference/fidl/language/error-catalog/label/_good.md” %}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0028-a.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
FIDL “lowers” doc comments to @doc attributes during compilation. In fact, any comment can be written directly in such a manner if so desired:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlc/tests/fidl/good/fi-0028-b.test.fidl" exclude_regexp="\/\/ (Copyright 20|Use of|found in).*" %}
Standalone doc comments are non-compilable from a technical perspective, but are also confusing semantically: what does it mean to “document” nothing? Unlike regular comments, doc comments get processed into structured documentation, and thus must be clear about which FIDL construct they are attached to.
