Fix doxygen warnings and remove javadocs (#2324)

* Fix doxygen warnings and remove javadocs * fix typo
HDFGroup · Dec 20, 2022 · c1e44d3 · c1e44d3
1 parent b9244a8
commit c1e44d3
Show file tree

Hide file tree

Showing 16 changed files with 28 additions and 63 deletions.
diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
@@ -854,7 +854,7 @@ INPUT_ENCODING         = UTF-8
 # *.vhdl, *.ucf, *.qsf and *.ice.
 
 FILE_PATTERNS  = H5*public.h H5*module.h H5*develop.h H5FD*.h \
-                 H5VLconnector.h H5VLconnector_passthru.h H5VLnative.h \
+                 H5VLconnector.h H5VLconnector_passthru.h H5VLnative.h H5PLextern.h \
                  H5Zdevelop.h \
                  H5version.h \
                  H5*.java \

diff --git a/doxygen/dox/ViewTools.dox b/doxygen/dox/ViewTools.dox
@@ -829,6 +829,7 @@ by simply viewing the specified dataset with the <code style="background-color:w
 \code
 h5dump -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" OMI-Aura.he5
 \endcode
+
 Subsetting narrows down the output that is displayed. In the following example, the first
 15x10 elements (-c "15,10") are specified, beginning with position (0,0) (-s "0,0"):
 \code
@@ -840,11 +841,8 @@ If using the shorthand method, specify:
     h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle[0,0;;15,10;]" -w 0 OMI-Aura.he5
 \endcode
 
-Where,
-\par The <code style="background-color:whitesmoke;">-d</code> option must be specified
-
-before
-\par subsetting options (if not using the shorthand method).
+Where, the <code style="background-color:whitesmoke;">-d</code> option must be specified
+before subsetting options (if not using the shorthand method).
 
 The <code style="background-color:whitesmoke;">-A 0</code> option suppresses the printing of attributes.
 

diff --git a/doxygen/dox/cookbook/Accessibility.dox b/doxygen/dox/cookbook/Accessibility.dox
@@ -1,6 +1,6 @@
 /** \page Accessibility
 
-\section Accessibility
+\section secAccessibility Accessibility
 
 \subsection CB_MaintainCompat Maintaining Compatibility with other HDF5 Library Versions
 

diff --git a/doxygen/dox/cookbook/Attributes.dox b/doxygen/dox/cookbook/Attributes.dox
@@ -1,6 +1,6 @@
 /** \page Attributes
 
-\section Attributes
+\section secAttributes Attributes
 
 \subsection CB_LargeAttributes Creating "Large" HDF5 Attributes
 

diff --git a/doxygen/dox/cookbook/Files.dox b/doxygen/dox/cookbook/Files.dox
@@ -1,6 +1,6 @@
 /** \page Files
 
-\section Files
+\section secFiles Files
 
 \subsection CB_FreeSpace Tracking Free Space in HDF5 Files
 

diff --git a/doxygen/dox/cookbook/Performance.dox b/doxygen/dox/cookbook/Performance.dox
@@ -1,6 +1,6 @@
 /** \page Performance
 
-\section Performance
+\section secPerformance Performance
 
 \subsection CB_MDCPerf Assessing HDF5 Metadata Cache Performance
 

diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml
@@ -4,13 +4,13 @@
   <navindex>
     <tab type="user" url="index.html" title="Overview" />
     <tab type="user" url="@ref GettingStarted" title="Getting started" />
-    <tab type="user" url="@ref Cookbook" title="Cookbook" />
     <tab type="user" url="@ref UG" title="User Guide" />
-    <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" />
-    <tab type="user" url="@ref GLS" title="Glossary" />
     <tab type="user" url="@ref RM" title="Reference Manual" />
-    <tab type="user" url="@ref TN" title="Technical Notes" />
+    <tab type="user" url="@ref GLS" title="Glossary" />
+    <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" />
     <tab type="user" url="@ref SPEC" title="Specifications" />
+    <tab type="user" url="@ref Cookbook" title="Cookbook" />
+    <tab type="user" url="@ref TN" title="Technical Notes" />
     <tab type="user" url="@ref RFC" title="RFCs" />
     <tab type="user" url="@ref FTS" title="Full-Text Search" />
     <tab type="user" url="@ref About" title="About" />

diff --git a/fortran/src/H5Pff.F90 b/fortran/src/H5Pff.F90
@@ -4305,31 +4305,6 @@ SUBROUTINE h5pset_f(prp_id, name, value, hdferr)
     CHARACTER(LEN=*), INTENT(IN)  :: name
     INTEGER         , INTENT(IN)  :: value
     INTEGER         , INTENT(OUT) :: hdferr
-  END SUBROUTINE h5pset
-
-!>
-!! \ingroup FH5P
-!!
-!! \brief Sets a property list value.
-!!
-!! \attention  \fortran_obsolete
-!!
-!! \param prp_id Property list identifier to modify.
-!! \param name   Name of property to modify.
-!! \param value  Property value, supported types are:
-!!               \li INTEGER
-!!               \li REAL
-!!               \li DOUBLE PRECISION
-!!               \li CHARACTER(LEN=*)
-!! \param hdferr \fortran_error
-!!
-!! See C API: @ref H5Pset()
-!!
-  SUBROUTINE h5pset_f(prp_id, name, value, hdferr)
-    INTEGER(HID_T), INTENT(IN) :: prp_id
-    CHARACTER(LEN=*), INTENT(IN) :: name
-    INTEGER,   INTENT(IN) :: value
-    INTEGER, INTENT(OUT) :: hdferr
   END SUBROUTINE h5pset_f
 !>
 !! \ingroup FH5P

diff --git a/java/src/Makefile.am b/java/src/Makefile.am
@@ -111,26 +111,22 @@ hdf5_java_JAVA =  \
 	${pkgpath}/HDFArray.java  \
 	${pkgpath}/HDFNativeData.java
 
-$(jarfile): classhdf5_java.stamp classes docs
+$(jarfile): classhdf5_java.stamp classes
 	$(JAR) cvf $@ -C $(JAVAROOT)/ $(pkgpath)
 
 hdf5_java_DATA = $(jarfile)
 
-.PHONY: docs classes
+.PHONY: classes
 
 WINDOWTITLE = 'HDF5 Java'
 DOCTITLE = '<h1>HDF5 Java Wrapper</h1>'
 SRCDIR = '$(pkgpath)'
 
-docs:
-	$(JAVADOC) -sourcepath $(srcdir) -d javadoc -Xdoclint:none -use -splitIndex -windowtitle $(WINDOWTITLE) -doctitle $(DOCTITLE) -J-Xmx180m -verbose -overview $(top_srcdir)/java/src/hdf/overview.html -classpath $(CLASSPATH_ENV) hdf.hdf5lib
-
 CLEANFILES = classhdf5_java.stamp $(jarfile) $(JAVAROOT)/$(pkgpath)/callbacks/*.class $(JAVAROOT)/$(pkgpath)/exceptions/*.class $(JAVAROOT)/$(pkgpath)/structs/*.class $(JAVAROOT)/$(pkgpath)/*.class
 
 clean:
 	rm -rf $(JAVAROOT)/*
 	rm -f $(jarfile)
-	rm -rf javadoc
 	rm -f classhdf5_java.stamp
 
 

diff --git a/java/src/hdf/hdf5lib/CMakeLists.txt b/java/src/hdf/hdf5lib/CMakeLists.txt
@@ -134,15 +134,3 @@ set_target_properties (${HDF5_JAVA_HDF5_LIB_TARGET} PROPERTIES FOLDER libraries/
 if (HDF5_ENABLE_FORMATTERS)
   clang_format (HDF5_JAVA_SRC_FORMAT ${HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES} ${HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES} ${HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES} ${HDF5_JAVA_HDF_HDF5_SOURCES})
 endif ()
-
-create_javadoc(hdf5_java_doc
-    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"
-    DOCTITLE "<h1>HDF5 Java Wrapper</h1>"
-    INSTALLPATH ${HDF5_INSTALL_DOC_DIR}
-    AUTHOR TRUE
-    USE TRUE
-    VERSION TRUE
-)
diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
@@ -301,6 +301,14 @@ Bug Fixes since HDF5-1.13.3 release
 
     Configuration
     -------------
+    - Remove Javadoc generation
+
+      The use of doxygen now supersedes the requirement to build javadocs. We do not
+      have the resources to continue to support two documentation methods and have
+      chosen doxygen as our standard.
+
+      (ADB - 2022/12/19)
+
     - Change the default for building the high-level tools
 
       The gif2hdf5 and hdf2gif high-level tools are deprecated and will be removed

diff --git a/src/H5Amodule.h b/src/H5Amodule.h
@@ -363,7 +363,7 @@
  * will be ignored by HDF5.
  *
  * The use of ASCII or UTF-8 characters is determined by the character encoding property. See
- * #H5Pset_char_encoding in the \ref RM.
+ * #H5Pset_char_encoding in the \ref RM.
  *
  * <h4>No Special I/O or Storage</h4>
  *

diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h
@@ -923,7 +923,7 @@
  *                containing thousands to millions of members. Links are stored in
  *                a fractal heap and indexed with an improved B-tree.
  *          \li The new implementation also enables the use of link names consisting of
- *              non-ASCII character sets (see H5Pset_char_encoding()) and is
+ *              non-ASCII character sets (see #H5Pset_char_encoding) and is
  *              required for all link types other than hard or soft links, e.g.,
  *              external and user-defined links (see the \ref H5L APIs).
  *

diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
@@ -729,7 +729,7 @@ H5_DLL herr_t H5Lexists_async(hid_t loc_id, const char *name, hbool_t *exists, h
  *          \p cset specifies the character set in which the link name is
  *          encoded. Valid values include the following:
  *          \csets
- *          This value is set with H5Pset_char_encoding().
+ *          This value is set with #H5Pset_char_encoding.
  *
  *          \c token is the location that a hard link points to, and
  *          \c val_size is the size of a soft link or user defined link value.
@@ -1525,7 +1525,7 @@ typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_
  *          \c cset specifies the character set in which the link name is
  *          encoded. Valid values include the following:
  *          \csets
- *          This value is set with H5Pset_char_encoding().
+ *          This value is set with #H5Pset_char_encoding.
  *
  *          \c address and \c val_size are returned for hard and symbolic
  *          links, respectively. Symbolic links include soft and external links

diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
@@ -1035,7 +1035,7 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g;
  *          When creating a fixed-length string datatype, \p size will
  *          be the length of the string in bytes. The length of the
  *          string in characters will depend on i the encoding used; see
- *          H5Pset_char_encoding().
+ *          #H5Pset_char_encoding.
  *
  *          ENUMs created with this function have a signed native integer
  *          base datatype.  Use H5Tenum_create() if a different integer base

diff --git a/src/H5VLconnector_passthru.h b/src/H5VLconnector_passthru.h
@@ -71,7 +71,7 @@ H5_DLL herr_t H5VLcmp_connector_cls(int *cmp, hid_t connector_id1, hid_t connect
  *                 - #H5I_MAP
  *                 - #H5I_ATTR
  *
- * \return \hid_t
+ * \return \hid_t{VOL connector}
  *
  * \note This routine is mainly targeted toward wrapping objects for
  *       iteration routine callbacks (i.e. the callbacks from H5Aiterate*,