On Thu, 3 Nov 2011, Andrew MacLeod wrote:
> Index: doc/extend.texi
Generally watch the line lengths in this patch - you should rewrap the
paragraphs to a width of about 70 characters (no more than 80) before
putting them on trunk. @item, @deftypefn etc. lines that can't be wrapped
may be longer - but paragraphs of text should have line lengths no more
than 80 characters.
> + @section Built-in functions for memory model aware atomic operations.
No "." at the end of a section name. There should be a corresponding
@node as well (normally have a one-to-one correspondence between nodes and
the structure of the printed manual). Don't try to put a section inside a
table (you can probably use @heading, but I'd still recommend keeping this
outside the section about __sync functions - or using @subsection to have
subsections for the __sync and __atomic cases).
> + The following builtins approximately match the requirements for
> + C++11 memory model. Many are similar to the ``__sync'' prefixed builtins,
> but
> + all also have a memory model parameter. These are all identified by being
> + prefixed with ``__atomic'', and most are overloaded such that they work
> + with multiple types.
@samp{__sync}, @samp{__atomic}, generally use @samp or @code for anything
that is quoting source code text (this includes type names such as size_t,
bits of function names such as compare_exchange, etc.). Not listed
separately below.
> + @item @var{type} __atomic_load_n (@var{type} *ptr, int memmodel)
> + @findex __atomic_load_n
As noted I think putting this inside the existing table is a mistake. The
preferred approach for new documentation is definitely to use @deftypefn
for functions - although converting the __sync_* documentation would be a
separate matter for anyone wishing to do so.
> + This builtin implements the generic version of __atomic_compare_exchange.
> The function is virtually identical to __atomic_compare_exchange_n, except
> the desired value is also a pointer.
The noun used in documentation is "built-in function" not "builtin". See
codingconventions.html. Likewise in several other places in this patch.
--
Joseph S. Myers
jos...@codesourcery.com
