Description
If I remember correctly, implementation-wise compile-flags and doc-flags are identical, compiletest simply forwards the respective flags to the underlying rustc/rustdoc invocation. So in practice it's merely a convention and show of intent to use one over the other. It's not like we can realistically enforce anything here (we certainly don't want to replicate rust{,do}c's CLI parsing inside compiletest).
With that said, I'd like us to consistently use //@ doc-flags for registering rustdoc-exclusive flags like --document-{private,hidden}-items, --crate-version, --generate-link-to-definition and keep using //@ compile-flags for flags that are shared by rustc and rustdoc like --crate-name, -Cmetadata in all rustdoc testsuites.
My main motivation would be to accommodate external tools that can parse compiletest directives and need to know which flags are okay to pass to rustc and rustdoc respectively.
Concrete example: A tool (that understands compiletest directives) wants to query the actual crate name of a crate it just documented in order to find the index page (doc/{crate_name}/index.html). For that it has to query rustc (!) via the print request --print=crate-name and pass along flags verbatim as obtained from e.g., compile-flags directives which may contain flags like --crate-name or --edition that (may) affect the crate name. However, if compile-flags directives contain rustdoc-specific flags like --generate-link-to-definition the rustc print request would fail for obvious reasons. If all rustdoc-specific flags were exclusively passed via doc-flags the tool wouldn't need to find workarounds for filtering them out.
C-discussion: Accept / reject?
Points of contention: (1) Churn inducing, (2) realistically not statically enforceable.