summaryrefslogtreecommitdiffstats
path: root/java/src/hdf/hdf5lib/package-info.java
diff options
context:
space:
mode:
authorAllen Byrne <50328838+byrnHDF@users.noreply.github.com>2022-09-14 20:44:24 (GMT)
committerGitHub <noreply@github.com>2022-09-14 20:44:24 (GMT)
commit45178c87a3099a9fef8bae6f7249ca306cf89629 (patch)
treecb404581365434d641e4d6303921613ef3432bd0 /java/src/hdf/hdf5lib/package-info.java
parentdcf3b54b6ef3ffe2093cfae81fe80cdb2bb53047 (diff)
downloadhdf5-45178c87a3099a9fef8bae6f7249ca306cf89629.zip
hdf5-45178c87a3099a9fef8bae6f7249ca306cf89629.tar.gz
hdf5-45178c87a3099a9fef8bae6f7249ca306cf89629.tar.bz2
develop Merge doxygen from 1.12 branch (#2095)
Diffstat (limited to 'java/src/hdf/hdf5lib/package-info.java')
-rw-r--r--java/src/hdf/hdf5lib/package-info.java114
1 files changed, 56 insertions, 58 deletions
diff --git a/java/src/hdf/hdf5lib/package-info.java b/java/src/hdf/hdf5lib/package-info.java
index c04b862..7ae4df9 100644
--- a/java/src/hdf/hdf5lib/package-info.java
+++ b/java/src/hdf/hdf5lib/package-info.java
@@ -12,10 +12,11 @@
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/**
+ @page HDF5LIB_UG HDF5 Java Package
* This package is the Java interface for the HDF5 library.
* <p>
- * This code is the called by Java programs to access the entry points of the HDF5 library. Each routine wraps
- a single
+ * This code is the called by Java programs to access the entry points of the HDF5 library.
+ * Each routine wraps a single
* HDF5 entry point, generally with the arguments and return codes analogous to the C interface.
* <p>
* For details of the HDF5 library, see the HDF5 Documentation at:
@@ -25,14 +26,13 @@
* <b>Mapping of arguments for Java</b>
*
* <p>
- * In general, arguments to the HDF Java API are straightforward translations from the 'C' API described in
- the HDF
- * Reference Manual.
+ * In general, arguments to the HDF Java API are straightforward translations from the 'C' API described
+ * in the HDF Reference Manual.
*
* <table border=1>
- * <caption><b>HDF-5 C types to Java types</b> </caption>
+ * <caption><b>HDF5 C types to Java types</b> </caption>
* <tr>
- * <td><b>HDF-5</b></td>
+ * <td><b>HDF5</b></td>
* <td><b>Java</b></td>
* </tr>
* <tr>
@@ -60,28 +60,27 @@
* <td>java.lang.String</td>
* </tr>
* <tr>
- * <td>void * <BR>
+ * <td>void * <br />
* (i.e., pointer to `Any')</td>
* <td>Special -- see HDFArray</td>
* </tr>
* </table>
* <b>General Rules for Passing Arguments and Results</b>
* <p>
- * In general, arguments passed <b>IN</b> to Java are the analogous basic types, as above. The exception is
- for arrays,
- * which are discussed below.
+ * In general, arguments passed <b>IN</b> to Java are the analogous basic types, as above. The exception
+ * is for arrays, which are discussed below.
* <p>
* The <i>return value</i> of Java methods is also the analogous type, as above. A major exception to that
- rule is that
+ * rule is that
* all HDF functions that return SUCCEED/FAIL are declared <i>boolean</i> in the Java version, rather than
- <i>int</i> as
+ * <i>int</i> as
* in the C. Functions that return a value or else FAIL are declared the equivalent to the C function.
- However, in most
+ * However, in most
* cases the Java method will raise an exception instead of returning an error code.
- * See <a href="#ERRORS">Errors and Exceptions</a> below.
+ * @see @ref ERRORS.
* <p>
* Java does not support pass by reference of arguments, so arguments that are returned through <b>OUT</b>
- parameters
+ * parameters
* must be wrapped in an object or array. The Java API for HDF consistently wraps arguments in arrays.
* <p>
* For instance, a function that returns two integers is declared:
@@ -104,12 +103,12 @@
*
* <p>
* All the routines where this convention is used will have specific documentation of the details, given
- below.
+ * below.
* <p>
* <b>Arrays</b>
* <p>
* HDF5 needs to read and write multi-dimensional arrays of any number type (and records). The HDF5 API
- describes the
+ * describes the
* layout of the source and destination, and the data for the array passed as a block of bytes, for instance,
*
* <pre>
@@ -118,52 +117,52 @@
*
* <p>
* where ``void *'' means that the data may be any valid numeric type, and is a contiguous block of bytes that
- is the
+ * is the
* data for a multi-dimensional array. The other parameters describe the dimensions, rank, and datatype of the
- array on
+ * array on
* disk (source) and in memory (destination).
* <p>
* For Java, this ``ANY'' is a problem, as the type of data must always be declared. Furthermore,
- multidimensional
+ * multidimensional
* arrays are definitely <i>not</i> laid out contiguously in memory. It would be infeasible to declare a
- separate
+ * separate
* routine for every combination of number type and dimensionality. For that reason, the
- * <a href="./hdf.hdf5lib.HDFArray.html"><b>HDFArray</b></a> class is used to discover the type, shape, and
- size of the
+ * <a href="./HDFArray.html"><b>HDFArray</b></a> class is used to discover the type, shape, and
+ * size of the
* data array at run time, and to convert to and from a contiguous array of bytes in synchronized static
- native C order.
+ * native C order.
* <p>
* The upshot is that any Java array of numbers (either primitive or sub-classes of type <b>Number</b>) can be
- passed as
+ * passed as
* an ``Object'', and the Java API will translate to and from the appropriate packed array of bytes needed by
- the C
+ * the C
* library. So the function above would be declared:
*
* <pre>
* public synchronized static native int H5Dread(long fid, long filetype, long memtype, long memspace, Object
- data);
+ * data);
* </pre>
* OPEN_IDS.addElement(id);
* and the parameter <i>data</i> can be any multi-dimensional array of numbers, such as float[][], or
- int[][][], or
+ * int[][][], or
* Double[][].
* <p>
- * <b>HDF-5 Constants</b>
+ * <b>HDF5 Constants</b>
* <p>
- * The HDF-5 API defines a set of constants and enumerated values. Most of these values are available to Java
- programs
- * via the class <a href="./hdf.hdf5lib.HDF5Constants.html"> <b>HDF5Constants</b></a>. For example, the
- parameters for
+ * The HDF5 API defines a set of constants and enumerated values. Most of these values are available to Java
+ * programs
+ * via the class <a href="./HDF5Constants.html"> <b>HDF5Constants</b></a>. For example, the
+ * parameters for
* the h5open() call include two numeric values, <b><i>HDFConstants.H5F_ACC_RDWR</i></b> and
* <b><i>HDF5Constants.H5P_DEFAULT</i></b>. As would be expected, these numbers correspond to the C constants
* <b><i>H5F_ACC_RDWR</i></b> and <b><i>H5P_DEFAULT</i></b>.
* <p>
- * The HDF-5 API defines a set of values that describe number types and sizes, such as "H5T_NATIVE_INT" and
- "hsize_t".
- * These values are determined at run time by the HDF-5 C library. To support these parameters, the Java class
- * <a href="./hdf.hdf5lib.HDF5CDataTypes.html"> <b>HDF5CDataTypes</b></a> looks up the values when initiated.
- The values
+ * The HDF5 API defines a set of values that describe number types and sizes, such as "H5T_NATIVE_INT" and
+ * "hsize_t".
+ * These values are determined at run time by the HDF5 C library. To support these parameters, the Java class
+ * <a href="./HDF5CDataTypes.html"> <b>HDF5CDataTypes</b></a> looks up the values when initiated.
+ * The values
* can be accessed as public variables of the Java class, such as:
*
* <pre>
@@ -175,31 +174,30 @@
* <p>
* <b>Error handling and Exceptions</b>
* <p>
- * The HDF5 error API (H5E) manages the behavior of the error stack in the HDF-5 library. This API is
- available from the
+ * The HDF5 error API (H5E) manages the behavior of the error stack in the HDF5 library. This API is
+ * available from the
* JHI5. Errors are converted into Java exceptions. This is totally different from the C interface, but is
- very natural
+ * very natural
* for Java programming.
* <p>
* The exceptions of the JHI5 are organized as sub-classes of the class
- * <a href="./hdf.hdf5lib.exceptions.HDF5Exception.html"> <b>HDF5Exception</b></a>. There are two subclasses
- of
- * <b>HDF5Exception</b>, <a href="./hdf.hdf5lib.exceptions.HDF5LibraryException.html">
- <b>HDF5LibraryException</b></a>
- * and <a href="./hdf.hdf5lib.exceptions.HDF5JavaException.html"> <b>HDF5JavaException</b></a>. The
- sub-classes of the
- * former represent errors from the HDF-5 C library, while sub-classes of the latter represent errors in the
- JHI5
- * wrapper and support code.
- * <p>
- * The super-class <b><i>HDF5LibraryException</i></b> implements the method '<b><i>printStackTrace()</i></b>',
- which
- * prints out the HDF-5 error stack, as described in the HDF-5 C API <i><b>H5Eprint()</b>.</i> This may be
- used by Java
- * exception handlers to print out the HDF-5 error stack.
+ * <a href="./HDF5Exception.html"> <b>HDF5Exception</b></a>. There are two subclasses
+ * of
+ * <b>HDF5Exception</b>, @ref ERRORSLIB <b>HDF5LibraryException</b>
+ * and @ref ERRORSJAVA <b>HDF5JavaException</b>.
+ * The sub-classes of the former represent errors from the HDF5 C library,
+ * while sub-classes of the latter represent errors in the JHI5 wrapper and support code.
+ * <p>
+ * The super-class <b><i>HDF5LibraryException</i></b> implements the method
+ * '<b><i>printStackTrace()</i></b>', which prints out the HDF5 error stack, as described
+ * in the HDF5 C API <i><b>@ref H5Eprint()</b>.</i> This may be
+ * used by Java
+ * exception handlers to print out the HDF5 error stack.
* <hr>
*
- * <b>See also: <a href="http://hdfgroup.org/HDF5/"> http://hdfgroup.org/HDF5"</a></b>
+ * @ref HDF5LIB
+ *
+ * <b>@see: <a href="http://hdfgroup.org/HDF5/"> HDF5"</a></b>
*
*/
package hdf.hdf5lib;