<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On 17 June 2015 at 16:59, 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:1px solid rgb(204,204,204);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=6dF8OEjVY0SMU2TeIrgllOIXh8V-GJaO-Gscazkr8zU&s=769gHq1-UMb6ohKUIAS31gs81wtmiI7xhZyV9Cc9_Fg&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 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></blockquote><div><br></div><div>Surely the ones in the pile of "flags accepted and ignored for compatibility" should be documented just that way.<br><br></div><div>The ones that "nobody really knows what they do" is obviously not quite so easy to solve and may need some digging [and inspecting whether they are really useful and needed? This particularly applies if "nobody" really means all the people involved in the LLVM/Clang projects, rather than the small subset that actively contribute to such a documentation project].<br><br>--<br></div><div>Mats <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
<br></blockquote></div><br></div></div>