[cfe-dev] Command line compiler options

[mats petersson]

On 17 June 2015 at 16:59, Reid Kleckner <rnk at google.com> wrote:

> 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.
>
> I think the attribute reference documentation (
> http://clang.llvm.org/docs/AttributeReference.html
> <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=>)
> 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.
>
> 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.
>
> 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.
>

Surely the ones in the pile of "flags accepted and ignored for
compatibility" should be documented just that way.

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].

--
Mats

>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20150617/372ba939/attachment.html>