Fix documentation for nc_put_att_text

[gsjaardema]

The nc_put_att_text function creates an attribute consisting of a single value unlike the other functions which can output more than one value. Update documentation to make this clear. The len argument is length of text and not the number of text items.

[edhartnett]

This is not correct. The trailing null may be included for C users.

[gsjaardema]

That is how i typically used it -- I would pass strlen(text)+1 as the length, but then I grepped the NetCDF source and saw that typically strlen(text) was passed as the argument. Not sure which is correct...

[edhartnett]

Neither is correct. It's up to the user.

Fortran does not use a NULL, so you might say don't bother writing one.

But then C programs must add a NULL every time they read the attribute. So if writing a bunch of netCDF files that will be read by a bunch of C programs, you might say always include the NULL.

So it is left up to the user. This may be unwise, but that's the way it has been and cannot be changed without breaking lots of code for someone. ;-)

[edhartnett]

Well in C there is no "text value". How about:

Pointer to an array of char with one or more elements; the array is the text value of the attribute.

[DennisHeimbigner]

Ed is right. It actually does allow multiple values, namely a sequence of chars.
Do not confuse text which is a vector of char, with String, which is a vector
of strings. I think calling it nc_put_att_text may have been a mistake
and it should have been something like nc_put_att_char.

[wkliao]

Just to share my 2 cents.

When I studied NetCDF at the beginning, I was often confused by _text APIs
with other APIs, especially, when encountering the error code NC_ECHAR.

My understanding of the name _text used in the NetCDF APIs is to differentiate
it from other APIs that read and write numerical values. The name _text is more
of describing the kind of data. Text data is not subject to be checked for numerical
boundaries, i.e. MIN and MAX, but for encoding checks, for example.

As for the argument len, its value does not include terminate null character. This
behavior matches with other numerical APIs to indicate the number of elements a
user would like to write to an attribute/variable. If the user buffer (argument value)
is of length more than len, then the API will only take the first len elements
without checking whether there is a null character at the end. If there is a null
character in between 1st and len^th elements, the API will faithfully write the
whole len length of characters, without stopping in the middle. If NetCDF does
check null terminate character, then argument len will be redundant.

[gsjaardema]

I guess the original documentation is correct considering the attribute as writing 1 or more chars which is similar to the other attribute functions writing 1 or more ints or 1 or more doubles.

I am fine with leaving everthing as it is, or if other find it confusing, iterating on this PR...

[edhartnett]

I have added an issue for this: #1512

I believe more than just a minor change is called for. I will add some explanation and put up a PR. When we have the C docs all sorted out, I will also add to the Fortran docs.

[edhartnett]

OK, I suggest this PR be taken down. I have done an extensive edit of the attribute docs, and have taken into account all comments from the PR. So the new docs should clarify all the issues raised here, as well as some differences between classic and netCDF-4/HDF5 format that were confusing. See #1515

[gsjaardema]

Thanks. Will close.

[edhartnett]

@gsjaardema thank you for pointing this out! While doing this I noticed some similar problems with the var documentation, so I suppose that's next for me. ;-)