Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify vlen string message documentation #3950

Merged
merged 1 commit into from
Jan 31, 2024
Merged

Clarify vlen string message documentation #3950

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 19 additions & 5 deletions doxygen/examples/H5.format.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10780,6 +10780,12 @@ <h4><a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a></h4>
<a name="ClassReference"></a>
<p>Class specific information for the Reference class (Class 7):</p>

<p>Note that for region references, the stored data is
a <a href="#GlobalHeapID">Global Heap ID</a> pointing to information
about the region stored in the global heap.
</p>


<div align="center">
<table class="desc">
<caption>
Expand Down Expand Up @@ -11118,6 +11124,11 @@ <h4><a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a></h4>
<a name="ClassVarLen"></a>
<p>Class specific information for the Variable-length class (Class 9):</p>

<p>Note that data with a variable length type is stored on the global heap.
Locations that would normally store the data directly (e.g. attribute message)
will instead contain a <a href="#GlobalHeapID">Global Heap ID</a>.
</p>

<div align="center">
<table class="desc">
<caption>
Expand Down Expand Up @@ -11276,7 +11287,7 @@ <h4><a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a></h4>
</tr>

<tr>
<td colspan="4"><br />Base Type<br /><br /></td>
<td colspan="4"><br />Parent Type Message<br /><br /></td>
Copy link
Collaborator

@jhendersonHDF jhendersonHDF Jan 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me, "base type" seems more appropriate since a variable-length type is similar to a container around some other type. That is to say, it seems to me to be more appropriate to call the variable-length type the parent type and the more fundamental type should be referred to as the base type.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation generally seems to use 'base type' and 'parent type' interchangeably. Enums and arrays are also described as having 'parent types' - would it be best to standardize all of these cases to refer to 'base types'? The field in the shared datatype structure is named parent, but that may not matter since it's internal.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I definitely think it would be good to standardize on a term, whether that's 'base type' or 'parent type'. The library definitely uses the two interchangeably fairly often, but I've personally always found 'parent type' to be confusing when used to refer to the type that a container type (vlen, array, compound) contains. The header comment for H5Tvlen_create even says "Create a new variable-length datatype based on the specified BASE_TYPE." and the parameter is base_id.

@derobins @fortnern Any opinions on this?

</tr>

</table>
Expand All @@ -11294,11 +11305,14 @@ <h4><a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a></h4>
</tr>

<tr>
<td><p>Base Type</p></td>
<td><p>Parent Type</p></td>
<td>
<p>Each variable-length type is based on some parent type. The
information for that parent type is described recursively by
this field.
<p>Each variable-length type is based on some parent type.
This field contains the datatype message describing that parent type.
In the case of nested variable-length types, this parent datatype message will
recursively contain all parent datatype messages.

Variable-length strings are considered to have the parent type `H5T_NATIVE_UCHAR`.
</p>
</td>
</tr>
Expand Down