[cfe-dev] Clang from the trenches...

[Aaron Ballman]

On Wed, Mar 19, 2014 at 11:35 PM, Chris Lattner <clattner at apple.com> wrote:
>
> On Mar 19, 2014, at 5:09 PM, Tim Hill <drtimhill at gmail.com> wrote:
>
>> I realize this is primarily a developers list, but wanted to give some feedback from the trenches having just switched from GCC to clang for one of our major software projects…
>>
>> The good:
>> — Superb diagnostic errors. These alone must have saved us countless hours in figuring out where the root of a compile-time problem lies. I still sometimes stare in disbelief at the uncanny way the compiler can point to the problem.
>>
>> — Wonderful static analyzer. Again, the quality here is one of the best i’ve seen in decades of coding.
>>
>> — Great code generation. I realize this is partly clang and partly LLVM, but the code output is easily as good as GCC for our project, even after many many hours comparing GCC and clang assembly files.
>>
>> — Compatibility. It’s impressive how well clang supports many of the entrenched GCC-isms that are so widely used.
>
> Great!
>
>> The bad:
>> — Documentation. I’m not going to pull my punches here .. it’s bad. I don’t mind terse, but some stuff doesn’t seem to be documented at ALL. Example: what are the valid inputs to the “-arch” (target CPU architecture) option? What are the valid inputs to the “-x” (language) option? Neither the man page, the —help option, nor the web docs show valid inputs. This really is frustrating, as it can take (literally) several hours of google searches to figure some of these things out.
>
> FWIW, I completely agree.  Does anyone have an idea of how we can improve this situation?  Maybe make this a GSoC project?

I had planned to (someday) take what we've started with attribute
documentation (AttrDocs.td) and apply it to compiler options. This
would allow us to follow the same migration path with option
documentation as with attributes, where documentation is table-driven
and semi-mandatory (you at least have to manually mark something as
undocumented). Whether this is a good GSoC project or not may be
debatable.

So that may be one possible... option (sorry, bad pun).

~Aaron