Mail Archives: djgpp/1998/02/05/02:49:49
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
- Raw text -