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

[Jean-Daniel Dupas]

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

-- Jean-Daniel