Add doxygen comments in H5Ppublic.h

[ChristopherHogan]

Adds doxygen-style documentation for the following functions:

• H5Pset_meta_block_size
• H5Pset_metadata_read_attempts
• H5Pset_multi_type
• H5Pset_object_flush_cb
• H5Pset_sieve_buf_size
• H5Pset_small_data_block_size
• H5Pset_all_coll_metadata_ops
• H5Pget_all_coll_metadata_ops

I also added a page (maybe_metadata_reads.dox) that corresponds to this page in the RM. I preserved the original structure by putting it and the associated functions in a "General Access Properties" group.

Example Code

I noticed a few different ways that people are adding example code to the documentation:

1. The \Code{} alias.
2. A <pre>...</pre> block
3. A \code ... \endcode block.

I think 3 is the most appropriate choice because it applies syntax highlighting to the code. However, two of the functions I documented (H5Pset_object_flush_cb and H5Pset_metadata_read_attempts) contain large code blocks with C-style comments, and since C does not allow nested /*...*/ comments, I had to put the example code in external files and \include them to get around this limitation.

On that same note, the doxygen EXAMPLE_PATH was not finding doxygen/examples, so I set it to use an absolute path via autoconf. I didn't make any CMake changes because it looks like we're not fully supporting CMake for doxygen yet.

Parallel Docs

I noticed that doxygen was not generating any documentation for functions declared in an H5_HAVE_PARALLEL block, even when I called configure with --enable-parallel. I believe that is because doxygen isn't including BUILDDIR/src/H5config.h. However, rather than helping doxygen find H5config.h it seemed better to always generate documentation for parallel-only functions (like the current RM) instead of only generating it if configure was called with --enable-parallel. For this reason, I added H5_HAVE_PARALLEL to doxygen's PREDEFINED variable.

[byrnHDF]

CMake for doxygen should be fully compatible with autotools.
What is the concern?

[ChristopherHogan]

CMake for doxygen should be fully compatible with autotools. What is the concern?

I see. I was only looking for doxygen stuff in CMakeLists.txt so I didn't see all the configuration in src/CMakeLists.txt. Thanks.

[byrnHDF]

CMake for doxygen should be fully compatible with autotools. What is the concern?

I see. I was only looking for doxygen stuff in CMakeLists.txt so I didn't see all the configuration in src/CMakeLists.txt. Thanks.

Yes, with CMake I was able to localize doxygen setup per source directory.

[ChristopherHogan]

Could someone point me to instructions for running clang-format?

[byrnHDF]

Could someone point me to instructions for running clang-format?

clang version should be version 10, this is available on jelly as LLVM module.
run bin/format_source

[gheber]

Good stuff. Thank you.