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

[Diego Novillo <dnovillo at redhat dot com>]

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.
First, thank you very much for documenting this.  I believe there is
some bugzilla PR that you are fixing with this patch.  Second, do you
have an FSF copyright assignment?

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.

> Index: configure.ac
> ===================================================================
> --- configure.ac	(revision 119061)
> +++ configure.ac	(working copy)
> @@ -21,6 +21,20 @@
>    permit yes|no|default)
>  AC_MSG_RESULT($enable_linux_futex)
>  
> +# We would like to our source tree to be readonly. However when releases or
s/to our/our/

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

> +@node omp_get_dynamic
> +@section @code{omp_get_dynamic} -- Whether Dynamic Teams Are Enabled
>                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                     Dynamic teams setting

> +@table @asis
> +@item @emph{Description}:
> +Whether the dynamic adjustment of the number of threads within a 
> +team is enabled or not.
Remove this.

> The function returns @code{true} if enabled, 
s/The/This/
> +@code{false} otherwise. Here, @code{true} and @code{false} represent 
> +their language-specific counterparts.

> +@node omp_get_max_threads
> +@section @code{omp_get_max_threads} -- Maximum Number Of Threads
> +@table @asis
> +@item @emph{Description}:
> +The maximum number of threads in a team if a parallel region
> +without a @code{num_threads} clause would be encountered.
> +
Return the maximum number of threads used for parallel regions that do
not use the clause @code{num_threads}.

> +@item @emph{C/C++}:
> +@multitable @columnfractions .20 .80
> +@item @emph{Prototype}: @tab @code{int omp_get_max_threads();}
> +@end multitable
> +
> +@item @emph{Fortran}:
> +@multitable @columnfractions .20 .80
> +@item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
> +@end multitable
> +
> +@item @emph{See also}:
> +@ref{omp_set_num_threads}, @ref{omp_set_dynamic}
> +
> +@item @emph{Reference}:
> +@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.3.
> +@end table
> +
> +
> +
> +@node omp_get_nested
> +@section @code{omp_get_nested} -- Whether Nested Parallel Regions Are Enabled
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
				     Nested parallel regions

> +@table @asis
> +@item @emph{Description}:
> +Whether nested parallel regions, i. e. team member spawning new teams, is 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +enabled or not. The function returns @code{true} if enabled, @code{false} 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +otherwise. Here, @code{true} and @code{false} represent their language-specific 
^^^^^^^^^^^^
> +counterparts.
> +
This function returns @code{true} if nested parallel regions are
enabled.  

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

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

> +threads attempted to set the lock before, one of them is chosen to, again, 
> +set the lock for itself.
> +
> +@node omp_test_nest_lock
> +@section @code{omp_test_nest_lock} -- Test And Set Nested Lock If Available
> +@table @asis
> +@item @emph{Description}:
> +Nested locks about to be set must not be uninitialized. Contrary to 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This needs rephrasing.

> +@code{omp_set_nest_lock}, @code{omp_test_nest_lock} does not block if 
> +the lock is not available. If the lock is already hold by the current 
s/hold/held/