Add javadoc to packages - HDFFV-11285 (#1197)

This commit is contained in:
Allen Byrne 2021-11-16 23:13:59 -06:00 committed by GitHub
parent 28e92647f0
commit b823ddc526
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 282 additions and 9 deletions

View File

@ -3293,6 +3293,7 @@
./java/src/hdf/hdf5lib/callbacks/H5P_prp_set_func_cb.java
./java/src/hdf/hdf5lib/callbacks/H5P_iterate_cb.java
./java/src/hdf/hdf5lib/callbacks/H5P_iterate_t.java
./java/src/hdf/hdf5lib/callbacks/package-info.java
./java/src/hdf/hdf5lib/exceptions/HDF5AttributeException.java
./java/src/hdf/hdf5lib/exceptions/HDF5BtreeException.java
@ -3318,6 +3319,7 @@
./java/src/hdf/hdf5lib/exceptions/HDF5ReferenceException.java
./java/src/hdf/hdf5lib/exceptions/HDF5ResourceUnavailableException.java
./java/src/hdf/hdf5lib/exceptions/HDF5SymbolTableException.java
./java/src/hdf/hdf5lib/exceptions/package-info.java
./java/src/hdf/hdf5lib/structs/H5_ih_info_t.java
./java/src/hdf/hdf5lib/structs/H5A_info_t.java
@ -3332,12 +3334,14 @@
./java/src/hdf/hdf5lib/structs/H5O_info_t.java
./java/src/hdf/hdf5lib/structs/H5O_native_info_t.java
./java/src/hdf/hdf5lib/structs/H5O_token_t.java
./java/src/hdf/hdf5lib/structs/package-info.java
./java/src/hdf/hdf5lib/H5.java
./java/src/hdf/hdf5lib/HDF5Constants.java
./java/src/hdf/hdf5lib/HDF5GroupInfo.java
./java/src/hdf/hdf5lib/HDFArray.java
./java/src/hdf/hdf5lib/HDFNativeData.java
./java/src/hdf/hdf5lib/package-info.java
./java/examples/Makefile.am
./java/examples/CMakeLists.txt

View File

@ -40,6 +40,11 @@ set (HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES
callbacks/Callbacks.java
)
set (HDF5_JAVADOC_HDF_HDF5_CALLBACKS_SOURCES
${HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES}
callbacks/package-info.java
)
set (HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES
exceptions/HDF5Exception.java
exceptions/HDF5IdException.java
@ -67,6 +72,11 @@ set (HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES
exceptions/HDF5SymbolTableException.java
)
set (HDF5_JAVADOC_HDF_HDF5_EXCEPTIONS_SOURCES
${HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES}
exceptions/package-info.java
)
set (HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES
structs/H5_ih_info_t.java
structs/H5A_info_t.java
@ -83,6 +93,11 @@ set (HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES
structs/H5O_token_t.java
)
set (HDF5_JAVADOC_HDF_HDF5_STRUCTS_SOURCES
${HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES}
structs/package-info.java
)
set (HDF5_JAVA_HDF_HDF5_SOURCES
HDFArray.java
HDF5Constants.java
@ -91,6 +106,11 @@ set (HDF5_JAVA_HDF_HDF5_SOURCES
H5.java
)
set (HDF5_JAVADOC_HDF_HDF5_SOURCES
${HDF5_JAVA_HDF_HDF5_SOURCES}
package-info.java
)
set (CMAKE_JNI_TARGET TRUE)
file (WRITE ${PROJECT_BINARY_DIR}/Manifest.txt
@ -114,7 +134,7 @@ add_dependencies (${HDF5_JAVA_HDF5_LIB_TARGET} ${HDF5_JAVA_JNI_LIB_TARGET})
set_target_properties (${HDF5_JAVA_HDF5_LIB_TARGET} PROPERTIES FOLDER libraries/java)
create_javadoc(hdf5_java_doc
FILES ${HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES} ${HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES} ${HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES} ${HDF5_JAVA_HDF_HDF5_SOURCES}
FILES ${HDF5_JAVADOC_HDF_HDF5_CALLBACKS_SOURCES} ${HDF5_JAVADOC_HDF_HDF5_EXCEPTIONS_SOURCES} ${HDF5_JAVADOC_HDF_HDF5_STRUCTS_SOURCES} ${HDF5_JAVADOC_HDF_HDF5_SOURCES}
OVERVIEW ${HDF5_JAVA_HDF5_SRC_DIR}/overview.html
CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
WINDOWTITLE "HDF5 Java"

View File

@ -64,8 +64,8 @@ import hdf.hdf5lib.structs.H5O_token_t;
* 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: <a
* href="http://hdfgroup.org/HDF5/">http://hdfgroup.org/HDF5/</a>
* For details of the HDF5 library, see the HDF5 Documentation at:
* <a href="http://hdfgroup.org/HDF5/">http://hdfgroup.org/HDF5/</a>
* <hr>
* <p>
* <b>Mapping of arguments for Java</b>
@ -162,8 +162,8 @@ import hdf.hdf5lib.structs.H5O_token_t;
* <p>
* For Java, this ``ANY'' is a problem, as the type of data must always be declared. Furthermore, multidimensional
* arrays are definitely <i>not</i> layed out contiguously in memory. It would be infeasible to declare a 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
* 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
* data array at run time, and to convert to and from a contiguous array of bytes in synchronized static 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
@ -187,8 +187,8 @@ import hdf.hdf5lib.structs.H5O_token_t;
* <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
* 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
* can be accessed as public variables of the Java class, such as:
*
* <pre>
@ -204,8 +204,8 @@ import hdf.hdf5lib.structs.H5O_token_t;
* JHI5. Errors are converted into Java exceptions. This is totally different from the C interface, but is 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
* 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

View File

@ -0,0 +1,27 @@
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/** All callback definitions must derive from the Callbacks interface. Any
* derived interfaces must define a single public method named "callback".
* You are responsible for deregistering your callback (if necessary)
* in its {@link Object#finalize} method. If native code attempts to call
* a callback which has been GC'd, you will likely crash the VM. If
* there is no method to deregister the callback (e.g. <code>atexit</code>
* in the C library), you must ensure that you always keep a live reference
* to the callback object.<p>
* A callback should generally never throw an exception, since it doesn't
* necessarily have an encompassing Java environment to catch it. Any
* exceptions thrown will be passed to the default callback exception
* handler.
*/
package hdf.hdf5lib.callbacks;

View File

@ -0,0 +1,31 @@
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/**
* <p>
* The package exceptions contains error classes for the Java HDF5 Interface.
* <p>
* There are two sub-classes of exceptions defined:
* <ol>
* <li>
* HDF5LibraryException -- errors raised the HDF5 library code
* <li>
* HDF5JavaException -- errors raised the HDF5 Java wrapper code
* </ol>
* <p>
* The HDF5LibraryException is the base class for the classes that represent specific error conditions.
* In particular, HDF5LibraryException has a sub-class for each major
* error code returned by the HDF5 library.
*
*/
package hdf.hdf5lib.exceptions;

View File

@ -0,0 +1,174 @@
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/**
* 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
* 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:
* <a href="http://hdfgroup.org/HDF5/">http://hdfgroup.org/HDF5/</a>
* <hr>
* <p>
* <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.
*
* <table border=1>
* <caption><b>HDF-5 C types to Java types</b> </caption>
* <tr>
* <td><b>HDF-5</b></td>
* <td><b>Java</b></td>
* </tr>
* <tr>
* <td>H5T_NATIVE_INT</td>
* <td>int, Integer</td>
* </tr>
* <tr>
* <td>H5T_NATIVE_SHORT</td>
* <td>short, Short</td>
* </tr>
* <tr>
* <td>H5T_NATIVE_FLOAT</td>
* <td>float, Float</td>
* </tr>
* <tr>
* <td>H5T_NATIVE_DOUBLE</td>
* <td>double, Double</td>
* </tr>
* <tr>
* <td>H5T_NATIVE_CHAR</td>
* <td>byte, Byte</td>
* </tr>
* <tr>
* <td>H5T_C_S1</td>
* <td>java.lang.String</td>
* </tr>
* <tr>
* <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.
* <p>
* The <i>return value</i> of Java methods is also the analogous type, as above. A major exception to 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
* in the C. Functions that return a value or else FAIL are declared the equivalent to the C function. 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.
* <p>
* Java does not support pass by reference of arguments, so arguments that are returned through <b>OUT</b> 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:
*
* <pre>
* h_err_t HDF5dummy( int *a1, int *a2)
* </pre>
*
* For the Java interface, this would be declared:
*
* <pre>
* public synchronized static native void HDF5dummy(int args[]);
* </pre>
*
* where <i>a1</i> is <i>args[0]</i> and <i>a2</i> is <i>args[1]</i>, and would be invoked:
*
* <pre>
* H5.HDF5dummy(a);
* </pre>
*
* <p>
* All the routines where this convention is used will have specific documentation of the details, given 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
* layout of the source and destination, and the data for the array passed as a block of bytes, for instance,
*
* <pre>
* herr_t H5Dread(long fid, long filetype, long memtype, long memspace, void *data);
* </pre>
*
* <p>
* where ``void *'' means that the data may be any valid numeric type, and is a contiguous block of bytes that is the
* data for a multi-dimensional array. The other parameters describe the dimensions, rank, and datatype of the 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
* arrays are definitely <i>not</i> layed out contiguously in memory. It would be infeasible to declare a 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
* data array at run time, and to convert to and from a contiguous array of bytes in synchronized static 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
* an ``Object'', and the Java API will translate to and from the appropriate packed array of bytes needed by 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);
* </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
* Double[][].
* <p>
* <b>HDF-5 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 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
* can be accessed as public variables of the Java class, such as:
*
* <pre>
* long data_type = HDF5CDataTypes.JH5T_NATIVE_INT;
* </pre>
*
* The Java application uses both types of constants the same way, the only difference is that the
* <b><i>HDF5CDataTypes</i></b> may have different values on different platforms.
* <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
* JHI5. Errors are converted into Java exceptions. This is totally different from the C interface, but is 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.
* <hr>
*
* <b>See also: <a href="http://hdfgroup.org/HDF5/"> http://hdfgroup.org/HDF5"</a></b>
**/
package hdf.hdf5lib;

View File

@ -0,0 +1,17 @@
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/** All structure definitions define java equivalents of the C structures needed
* by the C API calls. See the C API for information about the structures.
*/
package hdf.hdf5lib.structs;