<div dir="ltr"><div class="gmail_extra">I pretty much agree with everything people have mentioned so far, and wanted to suggest how we could go forward, assuming someone had the time.</div><div class="gmail_extra"><br></div><div class="gmail_extra">I think the attribute reference documentation (<a href="https://urldefense.proofpoint.com/v2/url?u=http-3A__clang.llvm.org_docs_AttributeReference.html&d=AwMFaQ&c=8hUWFZcy2Z-Za5rBPlktOQ&r=CnzuN65ENJ1H9py9XLiRvC_UQz6u3oG6GUNn7_wosSM&m=6dF8OEjVY0SMU2TeIrgllOIXh8V-GJaO-Gscazkr8zU&s=769gHq1-UMb6ohKUIAS31gs81wtmiI7xhZyV9Cc9_Fg&e=">http://clang.llvm.org/docs/AttributeReference.html</a>) is both comprehensive and readable, and is a good example of what we could do for flags. The gist is that when you add a new attribute, you have to explicitly add the Documentation variable or you get a build error. You can explicitly mark an attribute as undocumented, but usually this comes up in code review.</div><div class="gmail_extra"><br></div><div class="gmail_extra">I don't like that the docs are written with tablegen *and* rst syntax, but I think that's probably fixable by doing some kind of rst extension like Sphinx itself.</div><div class="gmail_extra"><br></div><div class="gmail_extra">For flags, I'm imagining that we'll have lots of commonly used flags (-fvisibility=, -fsanitize=, -fno-omit-frame-pointer) that we'll want to describe in detail. At the end, we'll have two big piles of flags without docs: flags that are accepted and ignored for compatibility, and flags which do something but nobody really knows what they do.</div></div>