[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: 20040703: Some NetCDF C interface doc issues (cont.)

> >To: address@hidden
> >From: der Mouse <address@hidden>
> >Subject: Some NetCDF C interface doc issues
> >Organization: ?
> >Keywords: 200407030332.i633WhaW006446
> 
> Me again. :-)
> 
> Now, I'm trying to actually write code to use the netcdf library.
> Everything seems to actually work as designed (so far as I've found, at
> least), but the documentation is lacking in a few respects, and there's
> one design weirdness (which can be looked on as a documentation lack,
> since the doc doesn't explain why it's done the way it is).
> 
> The documentation I'm talking about is
> http://my.unidata.ucar.edu/content/software/netcdf/guidec.txt as of
> 2004-06-28 20:46 UTC.
> 
> Note that this is not a complaint - I'd much rather have solid software
> with so-so doc than slickly documented junk.  But when I see something
> this good with a deficiency, I want to make it better!

Me too!

> 
> I will volunteer to write the missing doc content, if such a volunteer
> is wanted.  However, I note that the webpages advertise four different
> formats of documentation, which leads me to suspect that the master doc
> is kept in some internal format and postprocessed to generate the
> distributed doc, so I probably cannot do the markup that surrounds the
> content.  (In some cases, such as the missing NC_E* names in the lists
> of error conditions, this means there probably is little I can do.)

We are in the process of switching docs into texinfo format, an ASCII
format that works with GNU tools like makeinfo, and also can be turned
into printable manuals with Tex. The newly revised manuals will come
out with the next version of netCDF, 3.6.0, due to be released this
month.

Once we're back in texinfo, we will be able to accept changes to the
manuals as diffs. However, until we complete the switch, we can't
easily accept documentation edits from users.

Also in this revision of documentation, we've separated the
language-neutral features of netCDF into the NetCDF Users' Guide, and
we now have a manual for each language interface. 

> 
> * There is no explicit description of how to grow the unlimited
>   dimension of a dataset with an unlimited dimension.  (It appears to
>   suffice to simply store into elements above the current maximum, but
>   it would have been reassuring if this were explicitly stated
>   somewhere.)

I've added the following paragraph to the discussion of dimensions
(which explains the unlimited dimension):

To grow variables along the unlimited dimension, write the data using
any of the netCDF data writing functions, and specify the index of the
unlimited dimension to the desired record number. The netCDF library
will write however many records are needed (using the fill value to
fill missing data, unless that feature is turned off).

> 
> * A number of functions return names of things, such as variables and
>   dimensions, by storing into an array supplied by the caller.  There
>   is no explicit statement as far as I can tell about when the
>   resulting strings are or aren't NUL-terminated, especially if the
>   name is exactly NC_MAX_NAME characters long (for example, does the
>   array need to be dimensioned [NC_MAX_NAME+1], or does the caller need
>   to arrange any NUL termination that may be needed if the name is
>   NC_MAX_NAME long?).

This applies only to the C interface. I've changed the C interface
manual to say this:

Returned variable name. The caller must allocate space for the
returned name. The maximum possible length, in characters, of a
variable name is given by the predefined constant NC_MAX_NAME. (This
doesn't include the null terminator, so declare your array to be size
NC_MAX_NAME+1). The returned character array will be null-terminated.

> 
> * All the nc_put_var1_* functions take pointers to the data to store.
>   This makes no sense to me; why not simply pass the datum directly
>   rather than forcing the caller to allocate a variable to store it?

Just pass a pointer to the data with a & operator. For example:

int datum;
nc_put_var1_int(ncid, varid, index, &datum);

Or am I reading your question wrong? Do you really want to do
something like this?

nc_put_var1_int(ncid, varid, index, 99);

If so, you're right, that won't work. However it seems like few
programs would be writing a data constant with nc_put_var1_int. 

> * The lists of error conditions do not describe what the NC_* values
>   corresponding to the various error conditions are; indeed, the only
>   list I find of the NC_* error values is in netcdf.h!  This makes it
>   difficult to write code to handle particular errors more meaningfully
>   than the generic error code's string.  (For example, I'd much rather
>   be able to say "the dataset you've given me doesn't contain the
>   `time' variable this program expects" instead of the relatively
>   uninformative "Variable not found".)  Of course, I can go look in
>   netcdf.h and find NC_ENOTVAR, but this feels like improperly going
>   under the hood, with all the fragility issues attendent on that.

Good point. I will update the manuals to include the error codes. But
I can't do that right now, as I have to get home for the BBQ!

However, it is not going "under the hood" to get them from
netcdf.h. That file is a published interface that we don't change, so
it's perfectly safe to look there.

> 
> * There is no indication of whether the lists of error conditions are
>   exhaustive.  (This is admittedly a common problem with such lists,
>   even including many systems' section-2 manpages, and I don't
>   necessarily expect it to be fixed; I mention it largely for
>   completeness.)

The lists of error conditions are exhaustive for each version. What I
mean is, we may add errors from version to version, but we don't add
them without listing them in netcdf.h.

The only caveat here is that some errors are returned as unix system
codes. I don' t have an exhaustive list of those anywhere in the
docs, and it's unclear to me right now whether that is specified by
POSIX.

Thanks for the input!

Ed Hartnett,
Unidata