Message-Id: <199802050746.JAA09216@ankara.duzen.com.tr>
Comments: Authenticated sender is <mitch AT ankara DOT duzen DOT com DOT tr>
From: "S. M. Halloran" <mitch AT duzen DOT com DOT tr>
Organization: User RFC 822- and 1123-Compliant
To: Nate Eldredge <eldredge AT ap DOT net>
Date: Thu, 5 Feb 1998 09:47:22 +0200
MIME-Version: 1.0
Content-type: text/plain; charset=US-ASCII
Content-transfer-encoding: 7BIT
Subject: Re: Automatically seeding random numbers
CC: djgpp AT delorie DOT com
In-reply-to: <199802050139.RAA05660@adit.ap.net>
Precedence: bulk

On  4 Feb 98, Nate Eldredge was found to have commented thusly:

> At 04:11  2/4/1998 +0200, S. M. Halloran wrote:
> >The 
> >use of the functions in 'info gcc' (read from RHide) doesn't seem to 
> >be very well documented...
> It won't get fixed unless you specifically say which functions are poorly
> documented, and how they could be improved. Better yet would be to write
> better documentation yourself.
> 

I think I mentioned one function in that message (the time() 
function) that was not at all well-documented.  In truth, the 
author of the function/library must write the documentation since he 
is the one who wrote the source and is familiar with it.  However, 
since the source of the standard library is available, then it is 
only a matter of poring over the code to figure out what the function 
writer was trying to do.

Below is the current version for the description of the time() 
function.  The statements in "Return Value" section are not too 
informative...actually not at all informative.  The definition of 
time() indicates that it merely passes off the job of getting the 
time to gettimeofday(), and the documentation of gettimeofday() tells 
more without looking at its source, which I could not find anyway 
since the function is not defined in any source file in the same 
directory where time() is found (if someone can tell me how to use 
'grep' to recursively search through a tree, I would be grateful).

---------------begin current description for time() function--------
time
====

Syntax
------

     #include <time.h>

     time_t time(time_t *t);

Description
-----------

If T is not `NULL', the current time is stored in `*t'.

Return Value
------------

The current time is returned.

Example
-------

     printf("Time is %d\n", time(0));
---------------end current description for time() function--------

Now I submit (and never want to see again :) for your critical review 
and thorough judgment my own revised version.  Although I present it 
in the Unix man page style (which is probably a standard for 
documentation that those who develop the djgpp library might consider 
or re-consider as a style to use), its elements are easily re-edited 
to fit presentation style you prefer.  This page is almost a verbatim 
description of time() as implemented by USL, and there is a more 
careful explanation of the possible return values and argument values 
that can be used.

-------------begin revised description for time() function-----------
time()            DJGPP STANDARD LIBRARY CALLS     time()     

     NAME
          time - gets the system time

     SYNOPSIS
          #include <time.h>

          time_t time(time_t *sysclock);

     DESCRIPTION
          time returns the value of time  in  seconds  since  00:00:00
          UTC, January 1, 1970.

          If sysclock is non-zero, the return value is also 
          stored in  the location to which tloc points.

     SEE ALSO
          gettimeofday()

     NOTES     
          time fails and its actions are undefined if tloc  points  to
          an illegal address.

     DIAGNOSTICS
          Upon successful completion, time returns the value of  time.
          Otherwise,  a  value  of (time_t)-1 is returned and errno is
          set to indicate the error.
-------------end of revised description for time() function--------

Time permitting, I would be happy to assist in a 
documentation/re-documentation effort that more adequately describes 
the use of the standard library functions, assuming of course I can 
easily find the well-written, but not necessarily 
well-commented (although that helps), source code to pore over.
I am not sure how any such effort is organized now.  I assume that 
the function/library writer should make the initial attempt to 
describe what is going on, perhaps follow a guideline for doc 
preparation supervised by the authority over the system (DJ?), then 
submit the doc to a review panel for commenting &c., going back and 
forth between author and review panel until everybody thinks things 
are satisfactory.  How does the GNU group handle this organization?

Mitch Halloran
Research (Bio)chemist
Duzen Laboratories Group
Ankara   TURKEY
mitch AT duzen DOT com DOT tr

other job title:  Sequoia's (dob 12-20-95) daddy