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

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

der Mouse <address@hidden> writes:

> Thanks for the quick response!
> 
> > We are in the process of switching docs into texinfo format, [...]
> 
> The only potential problem I have with that is that - at least in my
> experience - it's rare to see manpages generated from texinfo source.
> Most people who use texinfo seem to think that if you aren't willing to
> put up with info files you don't deserve any doc.
> 
> Now, it's reasonably likely that that's an artifact of what I've seen
> texinfo documentation on (mostly GNU stuff) and that it's not actually
> a failing of texinfo at all.  It's just a bit of a concern for me,
> knowing as little as I do of your plans.
> 
> Does your reworking of the doc include breaking functions out into
> individual manpages, or at least separate pages for each group of
> closely related functions?  (For example, it would be reasonable to
> have a single page for all the nc_put_vara_* functions, with links to
> it from the individual functions' names.)
> 

We don't generate man pages from texinfo, but we do support man pages,
one for the fortran interface, and one for the C interface.  (In each
case there is just one man page for the entire interface.)


> >> * 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.
> 
> Yes, of course - but that demands that I allocate somewhere to store it
> in, since unary & can be applied only to lvalues.  Worse, it forces
> that variable into memory, since once its address is taken, its value
> must be pushed back into memory at any later point where control leaves
> the relevant module and the variable has not yet gone out of scope,
> even if its value is in fact dead.  (This matters because it reduces
> optimization possibilities.  I think C99 provides a keyword that allows
> a function to promise that it will not hang onto a pointer argument,
> thus fixing the optimization issue, but (a) I may be wrong and (b) even
> if not, using that would break compatability with pre-C99 compilers.)
> 
> > Or am I reading your question wrong?  Do you really want to do
> > something like this?
> 
> > nc_put_var1_int(ncid, varid, index, 99);
> 
> Exactly.  (Mutatis mutandis, that is.  See below.)
> 
> > 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.
> 
> Oh, the last arg doesn't have to be a constant, and in the case at hand
> it wasn't.  I wanted to do
> 
> nc_put_var1_float(dsid,v_load,&locv[0],int1/(float)int2);
> 
> but instead I had to allocate a variable, otherwise unused, to hold the
> quotient.  Thing is, I can't see anything that using a pointer allows
> you to do that you can't do at least as well without the pointer, which
> leaves me rather baffled about why you designed it that way.  Either
> I'm missing something or you did something gratuitously bizarre, and
> either way, I'm puzzled.

OK, now I see what you want.

As a practical matter, we can't change the meaning of the var1
functions, since they've been part of the interface for many years, and
changing them would break all the programs that use them. To
accommodate you we would have to add a new set of functions.

I agree that might be useful, but we are also concerned with keeping
the interface simple, which means we add new functions only with great
care, and for pressing need. So I suspect we'll just have to live with
this one.

> 
> >> * The lists of error conditions do not describe what the NC_* values
> >>    corresponding to the various error conditions are; [...]
> > 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!
> 
> Oh, there's no rush on any of this, no hurry at all.

I want to include it in this round of manual edits, which should get
released with 3.6.0 later this month.

> 
> >>    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.
> > 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.
> 
> Well, yes - what feels fragile is not assuming that, say, NC_ENOTVAR
> exists; it's assuming that NC_ENOTVAR is the value returned for the
> particular "no such variable" condition I care about.
> 
> >> * There is no indication of whether the lists of error conditions are
> >>   exhaustive.
> > The lists of error conditions are exhaustive for each version.  [...]
> 
> Good.  Maybe I could suggest changing the wording from "Possible causes
> of errors include" (which leaves open the possibility that there are
> others) to something more definite?

OK, I'll discuss this with Russ and see what he thinks. I agree that
if we're providing exhaustive lists (which I believe we are) then we
should say so.

> 
> > What I mean is, we may add errors from version to version, but we
> > don't add them without listing them in netcdf.h.
> 
> Well, no; the worry is whether you've added them to the code without
> adding them to the doc.  I've seen that happen far too often, usually
> with syscalls.
> 
> > The only caveat here is that some errors are returned as unix system
> > codes.
> 
> Oh, you mean things like (say) EROFS when trying to open for write a
> dataset that's on a filesystem mounted readonly, rather than a suitable
> NC_E* value instead?  Yes, it might be good to add a mention of cases
> where that can happen.  I've seen documentation that says things like
> 
>       foo() can also fail for any of the reasons given for open(2),
>       mmap(2), or close(2).
> 
> and it sounds as though something along those lines might be
> appropriate here (especially since you can't know all the possible
> failure modes for, say, open(), on the library user's system).
> 
> > 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.
> 
> I'm not sure what POSIX would - could! - have to say about it; I have
> trouble imagining POSIX prohibiting application developers from
> designing interfaces that include the use of E* error returns. :-)
> 
> On looking things over again, I notice an inconsistency (this quote
> >From the netcdf(3) manpage):
> 
>        char name[]
>               is the name of a dimension, variable, or attribute.
>               It shall begin with an alphabetic  character,  fol-
>               lowed  by  zero or more alphanumeric characters in-
>               cluding the underscore (`_') or hyphen (`-').  Case
> [...]
>               is NC_MAX_NAME.  Names that begin  with  an  under-
>               score  (`_') are reserved for use by the netCDF in-
>               terface.
> 
> Names that begin with an underscore are not allowed at all, according
> to the "It shall..." description, so it makes no sense to speak of
> their being reserved.

True! There have also been some changes in what is allowed in a name,
so we'll have to take a look at that topic!

> 
> It also might be nice to specify what character set's values of
> "alphabetic" and "alphanumeric" are used.  ASCII?  8859-1?  UTF-8?
> 

Good idea. At the moment, it's ASCII.

Ed