[cfe-dev] Command line compiler options

[Aaron Ballman]

On Thu, Jun 18, 2015 at 1:37 AM, Sean Silva <chisophugis at gmail.com> wrote:
>
>
> On Wed, Jun 17, 2015 at 8:59 AM, 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) 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.
>
>
> Yeah, AttributeReference is awesome! Mad props to Aaron!

Thank you! I also had command line options in mind when I was doing
that work, as it seemed like a natural extension. I think we have the
infrastructure in place to handle this, it's just a matter of
factoring out the doc generation from ClangAttrEmitter.cpp into
something a bit more agnostic, and then writing the logic for command
line flags.

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

That was the conclusion I came to as well. Also, but having the rst
inside of the tablegen, it is easier to control things like requiring
documentation and complaining if none exists.

~Aaron

>
>>
>>
>> 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.
>
>
> 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.
>
> AttributeRefrence also shows a good precedent to follow when it comes to
> features that are implemented for GCC/MSVC compatibility:
> http://clang.llvm.org/docs/AttributeReference.html#format-gnu-format
> http://clang.llvm.org/docs/AttributeReference.html#thread
>
> -- Sean Silva
>