<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Jun 16, 2015 at 10:34 PM, Justin Bogner <span dir="ltr"><<a href="mailto:mail@justinbogner.com" target="_blank">mail@justinbogner.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">Sean Silva <<a href="mailto:chisophugis@gmail.com">chisophugis@gmail.com</a>> writes:<br>
> On Tue, Jun 16, 2015 at 8:44 PM, Justin Bogner <<a href="mailto:mail@justinbogner.com">mail@justinbogner.com</a>> wrote:<br>
</span><span class="">>> Clang does not currently document its command line even remotely<br>
>> sufficiently. We have "clang --help" and the clang user's manual, which<br>
>> are both helpful but neither of which is really satisfactory.<br>
>><br>
>> The problem, as I see it, is that nobody has really stepped up to just<br>
>> write a thorough manual of what is available. We've often had<br>
>> discussions of how to automate writing this (through tablegen or<br>
>> otherwise), but these tend to lead to these two important results:<br>
>><br>
>> 1. Nobody's willing to do the work to design and implement something<br>
>>    satisfactory.<br>
>><br>
>> 2. Several people point out that automated documentation tends not to be<br>
>>    as readable and clear as hand-written output.<br>
><br>
> I can't find the bugzilla where I described this, but there's actually another<br>
> problem, which is potentially more serious. Even if we did magically have a<br>
> large body of documentation that covered a lot of these gaps, it's not a sure<br>
> thing that we would want to incorporate this content into our docs [1]. The<br>
> issue is that many of our options are specifically there for GCC or MSVC<br>
> compatibility, so providing an independent (duplicated) description of the<br>
> option opens the door to divergence.<br>
<br>
</span>The answer to "How do you use clang?" in 2009 was "man gcc". It was cute<br>
then, but it's embarrasing now.<br></blockquote><div><br></div><div>"The implementation of this {GCC,MSVC} option in our {GCC,MSVC} compatible driver follows that of {GCC,MSVC}  documented here: <link>". That's not embarrassing IMO.</div><div><br></div><div>-- Sean Silva</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<span class=""><br>
> Our current rough "policy" of documenting features of clang that are<br>
> not compatibility features (or where they are incompatible in some<br>
> way) is actually pretty economical and in line with SPOT/ DRY<br>
> principles.<br>
<br>
</span>DRY is about implementing software. Trying to apply it to documentation<br>
inevitably leads to terrible documentation, in my experience.<br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class=""><br>
> It also means that all of our bug reports are "bug in compatibility<br>
> with GCC/MSVC" and we can asymptotically approach compatibility<br>
> (i.e. fixable with patches). Compare this to "I, a user of your<br>
> compiler, relied on a feature that you documented as behaving in a<br>
> particular way, and now you are changing it" which leaves us between a<br>
> rock and a hard place: stay incompatible with the other compilers or<br>
> break our own compatibility promises (not fixable with patches; we are<br>
> now in the realm of social/political issues).<br>
<br>
</span>I don't necessarily disagree with you here, at least in the sense that I<br>
don't think we should document (for example) every gcc extension we<br>
implement in great detail. The issue at hand is the smaller question of<br>
"what flags does clang accept?". The answer today is "all of the gcc<br>
ones! Oh, but some of them do nothing, or aren't accepted at all. And<br>
there are clang specific ones - I think we documented a few of those in<br>
the clang user's manual, maybe."<br>
<br>
We can document which flags a particular version of clang accepts<br>
without stating "we implement feature X, it works exacly like blah, and<br>
we promise to support it forever". We can mitigate misunderstandings by<br>
stating that particular options are for compatibility when that's all<br>
they exist for, and I don't see why bugs in the documentation should be<br>
treated differently than any other bug.<br>
<div class=""><div class="h5"><br>
> It's an open question whether the open-source project wants to risk<br>
> that support problem, or whether there is a safe set of options we can<br>
> document without worrying about this; but arbitrarily thorough<br>
> documentation essentially turns any existing compatibility bugs (or<br>
> misunderstandings of a GCC/MSVC option on the part of the documenter)<br>
> into potentially "forever" support costs.<br>
><br>
> [1] suffice it to say I know at least one company that ships a ~100 page "C/<br>
> C++ Compiler Reference" with their clang-based platform toolchain<br>
><br>
> -- Sean Silva<br>
</div></div></blockquote></div><br></div></div>