[cfe-dev] Command line compiler options

[Sean Silva]

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!


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


>
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20150617/c616696a/attachment.html>