[cfe-commits] Updated and expanded Clang manual page (docs/tools/clang.pod)

[Jean-Daniel Dupas]

Le 28 nov. 2012 à 20:15, John McCall <rjmccall at apple.com> a écrit :

> On Nov 28, 2012, at 4:10 AM, Jean-Daniel Dupas <devlists at shadowlab.org> wrote:
>> Le 28 nov. 2012 à 01:37, John McCall <rjmccall at apple.com> a écrit :
>>> On Nov 21, 2012, at 10:40 AM, Jonathan de Boyne Pollard <J.deBoynePollard-newsgroups at NTLWorld.COM> wrote:
>>>> On 2012-11-21 16:19, Chris Lattner wrote:
>>>>> Definitely! Please send patches to the cfe-commits mailing list! 
>>>> 
>>>> The output of svn diff turns out to be larger, at 28KiB, than the file itself, which is 27KiB.  So I'm attaching the file as-is. Enjoy.  I might be persuaded to fill in some more of the missing bits.  (-:
>>>> <clang.pod>
>>> 
>>> First of all, thank you for doing this.  I think this is an excellent start.
>>> 
>>> I haven't read through the entire page yet, but I do have a major
>>> piece of feedback which (to be clear) I don't think should necessarily
>>> block this going into trunk.
>>> 
>>> The major complaint is about your audience.  Manual pages are
>>> user documentation, but you've got a lot in here that's more of a
>>> description of the clang *project* than a reference for the clang
>>> *program*.  For example, a typical user of this manual page does
>>> not need to know straight off that Clang is built on top of the LLVM
>>> project and that we have separate stages of compilation that build
>>> semantically-rich ASTs and then translate them into LLVM IR.
>>> 
>>> The man page should look basically like this:
>>> 
>>> 1.  Synopsis
>>> 2.  Brief description (a few paragraphs, easily scrolled past) of
>>>   capabilities of tool, possibly with copious forward-references
>>> 3.  Discussion of basic usage
>>> 4.  Detailed options reference
>>> 5.  Architectural details if user-relevant
>>> 6.  End-matter
>>> 
>>> So personally I would rewrite the introduction somewhat like this:
>>> 
>>> B<clang> is a C, C++, Objective-C, and Objective-C++ compiler.  It
>>> fully supports the C11 and C++11 language standards as well as a
>>> robust set of language extensions.  Its option syntax is (with one
>>> exception, see OPTIONS below) a superset of that of the the
>>> POSIX.1:2008 C<c99> utility.
>> 
>> Maybe this introduction is a little too optimistic about the C11 full support.
>> While clang supports the most useful C11 extensions, I'm not sure it can claim full support yet (for instance, _Noreturn and _Thread_local keywords support is not implemented at all).
> 
> Good point;  we should only claim C99 conformance.  Would you mind filing PRs about the missing extensions, though?  Both of those should be quite straightforward.
> 

There is already a bug for noreturn with interesting comments: http://llvm.org/bugs/show_bug.cgi?id=13818

And I filled one for _Thread_local: http://llvm.org/bugs/show_bug.cgi?id=14479

-- Jean-Daniel