Re: [Patch/gfortran] Intrinsic docs

[Tobias Schlüter <tobias dot schlueter at physik dot uni-muenchen dot de>]

Jerry DeLisle wrote:
> Attached is patch that adds documentation for the following intrinsics:
> 

Thanks!

> + * @code{COUNT}:         COUNT,     Count logical .TRUE. occurrences in array mask

This looks weird to me, but you're a native speaker.  I would have said
something like "Count occurences of .TRUE. in an array"

> + * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine

I think something more informative like "Return the current CPU time" would be
in place.

>   @node ACOS
> ! @section @code{ACOS} --- Arccosine function 
>   @findex @code{ACOS} intrinsic
>   @findex @code{DACOS} intrinsic
> ! @cindex arccosine
>   
>   @table @asis
>   @item @emph{Description}:
> ! @code{ACOS(X)} computes the arccosine of its @var{X}.

Again, you're the native speaker, but why 'its'? Doesn't something like 'of
its argument X' or simply 'of X' sound more natural?

> *************** end program test_cmplx
> *** 1410,1415 ****
> --- 1418,1508 ----
>   
>   
>   
> + @node COMMAND_ARGUMENT_COUNT
> + @section @code{COMMAND_ARGUMENT_COUNT} --- Argument count function 
> + @findex @code{COMMAND_ARGUMENT_COUNT} intrinsic
> + @cindex command argument count
> + 
> + @table @asis
> + @item @emph{Description}:
> + @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the command line when the containing program was invoked.

^^^^ overlong line
> + @node CONJG
> + @section @code{CONJG} --- Complex conjugate function 
> + @findex @code{CONJG} intrinsic
> + @findex @code{DCONJG} intrinsic
> + @cindex complex conjugate
> + @table @asis
> + @item @emph{Description}:
> + @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)} then the result is @code{(x, -y)}

again, please format lines to less than 80 columns.

> *************** elemental function
> *** 1438,1444 ****
>   @end multitable
>   
>   @item @emph{Return value}:
> ! The return value has same type and kind than @var{X}.
>   
>   @item @emph{Example}:
>   @smallexample
> --- 1531,1537 ----
>   @end multitable
>   
>   @item @emph{Return value}:
> ! The return value has same type and kind as @var{X}.

Is there a 'the' missing?

> + @node COUNT
> + @section @code{COUNT} --- Count function
> + @findex @code{COUNT} intrinsic
> + @cindex count
> + 
> + @table @asis
> + @item @emph{Description}:
> + @code{COUNT(MASK[,DIM])} counts the number of @code{.TRUE.} elements of @var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{MASK}.

Overlong.

> + @node CPU_TIME
> + @section @code{CPU_TIME} --- CPU time subroutine

Again, something more informative would be in place.

> + @findex @code{CPU_TIME} intrinsic
> + @cindex CPU_TIME
> + 
> + @table @asis
> + @item @emph{Description}:
> + Determine the CPU time in a processor-dependent way in seconds.  This is useful for testing segments of code to determine execution time.

"Returns a default REAL value indicating the CPU time spent in the process in
seconds" maybe?  What kind of processor-dependency are you talking about?

(I'll stop mentioning overlong lines)

> + @node DATE_AND_TIME
> + @section @code{DATE_AND_TIME} --- Date and time subroutine
> + @findex @code{DATE_AND_TIME} intrinsic
> + @cindex DATE_AND_TIME
> + 
> + @table @asis
> + @item @emph{Description}:
> + @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and time information from the real-time system clock.  @var{DATE} is @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, representing the difference with respect to Coordinated Universal Time (UTC).  Unavailable time and date parameters return blanks.
> + 
> + @var{VALUES} is @code{INTENT(OUT)} and provides the following
> + 

there's something missing here.

> + @item @emph{Arguments}:
> + @multitable @columnfractions .15 .80
> + @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.
> + @end multitable

"... shall be any numeric type"?  I don't think wildcards are appropriate.

Thanks,
- Tobi