Re: [patch, libgomp, docs] adding documentation to libgomp

[Daniel Franke <franke dot daniel at gmail dot com>]

:ADDPATCH libgomp:

On Wednesday 29 November 2006 00:36, Diego Novillo wrote:
> Daniel Franke wrote on 11/23/06 18:09:
> > 2006-11-24  Daniel Franke  <franke.daniel@gmail.com>
> >
> > 	PR libgomp/28209
> > 	* libgomp.texi: New file.
> > 	* configure.ac: Add --enable-generated-files-in-srcdir option.
> > 	* Makefile.am Add info, dvi, pdf, html targets. On request, copy files
> > to srcdir.
> > 	* Makefile.in: Regenerated.
> > 	* config.h.in: Regenerated.
> > 	* testsuite/Makefile.in: Regenerated.
> > 	* NOTES: Removed.
>
> I can't approve the configury bits.  The documentation looks OK with
> some changes below.  You'll need to have a doc maintainer go over the
> texinfo formatting.


Done.

Tested info, dvi, pdf and html targets on i686-pc-linux-gnu.
Please find the revised patch attached and some comments below.

Now waiting for approval of the texinfo/configury parts.

Regards
	Daniel


> > +@menu
> > +* omp_get_dynamic::          Whether Dynamic Teams Are Enabled
> > +* omp_get_max_threads::      Maximum Number Of Threads
> > +* omp_get_nested::           Whether Nested Parallel Regions Are Enabled
> > +* omp_get_num_procs::        Number Of Processors Online
> > +* omp_get_num_threads::      Size Of The Active Team
> > +* omp_get_thread_num::       Current Thread ID
> > +* omp_in_parallel::          Whether A Parallel Region is Active
> > +* omp_set_dynamic::          Enable/Disable Dynamic Teams
> > +* omp_set_nested::           Enable/Disable Nested Parallel Regions
> > +* omp_set_num_threads::      Set Upper Team Size Limit
> > +@end menu
> > +
>
> Does the right column need to be capitalized like that?  It looks
> pretty bad.  Likewise in other menus.

No special reason. Changed the right column, but the beginning of the line and 
abbreviations, to lowercase.


> > +@node omp_set_lock
> > +@section @code{omp_set_lock} -- Wait For And Set Simple Lock
> > +@table @asis
> > +@item @emph{Description}:
> > +Simple locks about to be set must not be uninitialized. The calling
> > thread
>
>    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>    I don't know what you are trying to say here.

This now reads:
"Before setting a simple lock, the lock variable must be initialized by 
@code{omp_init_lock}."



> > +@node omp_unset_lock
> > +@section @code{omp_unset_lock} -- Unset Simple Lock
> > +@table @asis
> > +@item @emph{Description}:
> > +Simple locks about to be unset must not be in a locked state and held by
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Better move this to the end of the paragraph
>
> > +the thread executing the routine. The lock becomes unlocked. If one ore
> > more
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^
>                                      Non-sequitur.

Ouch. That one was as wrong as it can get.
Now, this reads:
"A simple lock about to be unset must have been locked by @code{omp_set_lock}
or @code{omp_test_lock} before. In addition, the lock must be held by the 
thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked."


Similar changes where made for nested locks.

Attachment: libgomp.info.patch.gz
Description: GNU Zip compressed data