Merge pull request pmem#1214 from KFilipek/doc_exceptions

[doxygen] add description for "exceptions" group
PersistentMemory · Oct 14, 2021 · 3cc48e1 · 3cc48e1
2 parents fe78a16 + 8fc76b5
commit 3cc48e1
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 3 deletions.
diff --git a/doc/groups_definitions.dox b/doc/groups_definitions.dox
@@ -163,4 +163,30 @@
 /** @defgroup data_view Data View*/
 /** @defgroup synchronization Synchronization Primitives*/
 /** @defgroup primitives Primitives*/
-/** @defgroup exceptions Exceptions*/
+/** @defgroup exceptions Exceptions
+  * Possible exceptions that could be thrown by the libpmemobj++.
+  *
+  * In runtime, some operations may fail, then all you need is to catch the exception.
+  * Every pmem exception has **std::runtime_error** in its inheritance tree
+  * and contains proper message with an error description.
+  * All exceptions can be caught using just **std::runtime_error**.
+  * Look at the list on this page to explore all exceptions with their descriptions.
+  *
+  * Transaction handles uncaught exceptions thrown inside its scope, then aborts
+  * and rethrow the previous exception. That way you never loose the original
+  * exception and at the same time, the transaction state is handled
+  * properly by the library.
+  *
+  * Let's consider following example:
+  * @snippet examples/mpsc_queue/mpsc_queue.cpp mpsc_main
+  *
+  * There are plenty of try-catch blocks placed to handle possible errors that can happen in some conditions.
+  * E.g. @ref pmem::obj::pool<T>::open can lead to @ref pmem::pool_error.
+  * Next exception, **std::exception**, is placed to handle possible errors during allocation,
+  * coming from @ref pmem::obj::make_persistent. Worth being careful using every new function
+  * because some of exceptions are not obvious, e.g., pmem::obj::pool<T>::close
+  * at the end of the code which may throw **std::logic_error**.
+  *
+  * You should check every function you will use in context of possible
+  * exceptions and then handle them to avoid crash.
+  **/
diff --git a/examples/mpsc_queue/mpsc_queue.cpp b/examples/mpsc_queue/mpsc_queue.cpp
@@ -80,6 +80,7 @@ single_threaded(pmem::obj::pool<root> pop)
 
 //! [mpsc_queue_single_threaded_example]
 
+//! [mpsc_main]
 int
 main(int argc, char *argv[])
 {
@@ -120,3 +121,4 @@ main(int argc, char *argv[])
 	}
 	return 0;
 }
+//! [mpsc_main]
diff --git a/include/libpmemobj++/pexceptions.hpp b/include/libpmemobj++/pexceptions.hpp
@@ -78,7 +78,7 @@ exception_with_errormsg(Args &&... args)
  * Custom pool error class.
  *
  * Thrown when there is a runtime problem with some action on the
- * pool.
+ * pool, e.g., object wasn't in a pool, invalid pool handle, etc.
  * @ingroup exceptions
  */
 class pool_error : public std::runtime_error {
@@ -90,6 +90,8 @@ class pool_error : public std::runtime_error {
  * Custom pool error class.
  *
  * Thrown when there is an invalid argument passed to create/open pool.
+ * Specialization of pool_error, which is thrown
+ * when creating/opening pool failed.
  * @ingroup exceptions
  */
 class pool_invalid_argument : public pool_error {
@@ -100,7 +102,8 @@ class pool_invalid_argument : public pool_error {
 /**
  * Custom transaction error class.
  *
- * Thrown when there is a runtime problem with a transaction.
+ * Thrown when there is a runtime problem with a transaction, e.g.,
+ * when the transaction is in the wrong stage, or on transaction abort.
  * @ingroup exceptions
  */
 class transaction_error : public std::runtime_error {