Document 'return-and-read' fields in API context

[mattjala]

The documentation for API contexts states there are four types of fields:

• property lists
• internal fields
• cached fields with a <field>_valid flag that do not cause their underlying property list to be modified
• return-only properties with a <field>_set flag that cause the underlying property list to be modified when the API context is popped, but are never queried internally by the library

However, there are several fields that contain both a <field>_valid and <field>_set flag. These fields can cause the input property list to be modified, may be queried internally by the library by functions of the form H5CX\_get\_<field>(), and can use cached values for reads similarly to cached fields. The specific fields are:

• actual_selection_io_mode
• mpio_local_no_coll_cause
• mpio_global_no_coll_cause
• no_selection_io_cause

This PR coins the term 'return-and-read fields' for these cases and documents them in the H5CX_t documentation, as well as pointing out some potentially unintuitive facts about them:

• the <field>_set flag only indicates whether the context has ever performed a set operation on this field. Later reads from the property list which overwrite the value stored on the context do not modify the set flag. As such, if a set operation is followed by an internal query, the modification of the property list at API context pop time will be redundant (since the value in the context will already match the property list's value).

• the <field>_valid flag only indicates whether the context has ever been populated with a value from the original property list. The H5CX_set_<field> routines don't interact with this flag at all, and so both of the following are possible:

  • the field is never read, and is only written by H5CX_set_<field>. The context then contains a meaningful value, but <field>_valid is false.
  • the field is read, but is overwritten on the context by H5CX_set_<field>. The context contains a value that is not from the underlying property list, but <field>_valid is true.