<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jun 17, 2015 at 8:59 AM, Reid Kleckner <span dir="ltr"><<a href="mailto:rnk@google.com" target="_blank">rnk@google.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><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=kFpDSMS55yvA1zEQcUqJyPfqgksSbQ5n1H-EmHujRoc&s=NfNOa23cjqaJ89htmOLi5T5rM66QeUiIZevsyya47VE&e=" target="_blank">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></blockquote><div><br></div><div>Yeah, AttributeReference is awesome! Mad props to Aaron!</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><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></blockquote><div><br></div><div>IIRC for this use case it is sort of inevitable. You want something like TableGen to factor out commonality and something like rst for the prose. It's either TableGen inside rst or rst inside TableGen, and rst inside TableGen seems to work pretty well.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><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></blockquote><div><br></div><div>Another thing I love about AttributeReference is that if something is Undocumented, then it is trivially easy to know where to go if you get an itch to document it. We all periodically go on yak hunts, and sometimes we end up diving into particular obscure command line argument/attribute and what it actually means/how we implement it. Improving the documentation is a very satisfying way to finish that phase of the yak hunt. This partially alleviates the "nobody is actually working on this full time" problem.</div><div><br></div><div>AttributeRefrence also shows a good precedent to follow when it comes to features that are implemented for GCC/MSVC compatibility:</div><div><a href="https://urldefense.proofpoint.com/v2/url?u=http-3A__clang.llvm.org_docs_AttributeReference.html-23format-2Dgnu-2Dformat&d=AwMFaQ&c=8hUWFZcy2Z-Za5rBPlktOQ&r=CnzuN65ENJ1H9py9XLiRvC_UQz6u3oG6GUNn7_wosSM&m=kFpDSMS55yvA1zEQcUqJyPfqgksSbQ5n1H-EmHujRoc&s=GIQ62DlAyk8INaOAwvvTdun2DFozskWy-1G8ht8n0tk&e=">http://clang.llvm.org/docs/AttributeReference.html#format-gnu-format</a><br></div><div><a href="https://urldefense.proofpoint.com/v2/url?u=http-3A__clang.llvm.org_docs_AttributeReference.html-23thread&d=AwMFaQ&c=8hUWFZcy2Z-Za5rBPlktOQ&r=CnzuN65ENJ1H9py9XLiRvC_UQz6u3oG6GUNn7_wosSM&m=kFpDSMS55yvA1zEQcUqJyPfqgksSbQ5n1H-EmHujRoc&s=z_yQOm5qftevYNtCcdP5gFLM_wDn4Nbsm4Fu0FgRUHc&e=">http://clang.llvm.org/docs/AttributeReference.html#thread</a><br></div><div><br></div><div>-- Sean Silva </div></div><br></div></div>