Re: cxx-mem-model merge [3 of 9] doc

[Andrew MacLeod <amacleod at redhat dot com>]

On 11/03/2011 08:04 PM, Joseph S. Myers wrote:
> 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.
how very 80's!  To be honest, I didn't realize I had full length 
paragraphs. I would have sworn i had taken care of 80 column issues...

Done.

> > + @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).
section inside a table?  yoinks. that wasn't obvious to me at all.  oops.

I make no pretences to understand .texi stuff :-P  but that was a clear 
oversight.
> > + 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.
OK, I think I covered those.

> > + @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.
I clearly missed something here... I didnt even realize I was in a table 
:-P   odd tho, because the output looked decent enough that I never 
noticed I was doing something whacky..   converted to @deftypefn

> > + 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.
Done.


So here is the updated patch.  Given my vast and deep knowledge of tex, 
I expect a few iterations :-)  It seems OK when I look at it, of course, 
it did before too :-P

Oh, and changes to md.texi as well.
Andrew

Attachment: doc2.diff
Description: Text document