Reference Manual in Doxygen


#1

Please take a look at this page and let us know what you think (in this thread)! We are finishing up H5P and tidying up a few other things.

Kudos to the Eigen project where we found a lot of inspiration.

Don’t get too excited, the survey link isn’t live (yet). :sunglasses:

Please leave any comments in this thread, or create a new more specific thread.

We would also like to know which of the technical documents you’d like to see in this format. For example, take a look at API Compatibility Macros.

And you can get involved! Keep an eye on the doxygen folder in the doxygen2 branch, eventually develop, or create a PR.

G.


#2

It looks good for a start! Of course, lots of work to get all the info there and up to date.

The left panel contains some references to external links, such as the glossary or user guide. I’d think such should be somehow indicated that clicking those leaves the doxygen page.

What would make sense is to also have various examples in this doxygen documentation, because those examples would then directly link to the respective function documentation, and the functions itself can also list the examples where they are used.

Just as comment to the prominent paragraph on " C++ Developers using HDF5 C-API functions beware:" This text seems to refer to the usage of exceptions within C++ code and particularly in callback functions. That seems implicitly clear, but I guess that this should be stated more prominently since usage of exceptions is not that all common (but of course it is in the HDF5 C++ API, even overly common there). It should be rather clear to C++ developers that C function callbacks don’t support the C++ exception stack. Another issue may be concerning C++20 coroutines… I am not sure how that would perform if a callback function yields execution to another routine which also does HDF5 calls, as this is not exactly same as multithreading. Something for future investigations, just to mention it at this occasion.


#3

Good point. Of course, we’d hope for those redirects to go away completely at some point. But then, what’s our record on the last transition? :disappointed:

Yes, there are a few mickey mouse examples here and there, but there should also be a more extensive collection, e.g., as part of the cookbook.

Again, excellent point. Let’s work on a better formulation! (At least we are at a point where we have a Doxygen alias for it and changing it in one place will fix it everywhere :smiley:)

Ditto. (I suspect it’ll deadlock because the next HDF5 call won’t be able to acquire the library lock. To be investigated…)

G.


#4

How about a formulation like this RE: C/C++?

Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). When used in C++ code, the corresponding callbacks may use the full list of C++ types and functions provided that the callbacks return normally. This behavior is necessary for the HDF5 library to manage its resources and maintain a consistent state. In particular, exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, C++20 coroutines cannot be used as callbacks, since they do not support plain return statements.


#5

Suggestion:

Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C setjmp/longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a catch(…) statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior.


#6

Thanks. Any suggestions for Technical Notes & Specs. we should migrate first. I put up a few examples:

Let me know!
G.


#7

Both sections look good and clean. It’s an overwhelming amount of information there, but I don’t know how to make it easier digestible. Maybe the specifications could be split up in multiple pages such that not all is one page; but then, for those who want to delve into the details, it may be good to have all on one page.