delete_persistent: extend doxygen documentation

Setting ptr to null after calling delete_persistent is required to
ensure proper recovery.

Author: igchor

examples/doc_snippets/make_persistent.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018, Intel Corporation
+ * Copyright 2016-2020, Intel Corporation
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -81,6 +81,10 @@ make_persistent_example()
 
 		// transactionally delete the object, ~compound_type() is called
 		delete_persistent<compound_type>(proot->comp);
+
+		// set pointer to null so that after restart it's known whether
+		// compound_type is still allocated or not
+		proot->comp = nullptr;
 	});
 
 	// throws an transaction_scope_error exception
@@ -139,6 +143,10 @@ make_persistent_array_example()
 		// transactionally delete arrays , ~compound_type() is called
 		delete_persistent<compound_type[]>(proot->comp, 20);
 		delete_persistent<compound_type[3]>(arr1);
+
+		// set pointer to null so that after restart it's known whether
+		// compound_type is still allocated or not
+		proot->comp = nullptr;
 	});
 
 	// throws an transaction_scope_error exception

include/libpmemobj++/make_persistent.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2019, Intel Corporation
+ * Copyright 2016-2020, Intel Corporation
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -133,6 +133,9 @@ make_persistent(Args &&... args)
  * object's destructor before freeing memory. Cannot be used for array
  * types.
  *
+ * To ensure that proper recovery is possible, ptr should be set to null after
+ * delete_persistent call and within the same transaction.
+ *
  * @param[in,out] ptr persistent pointer to an object that is not an
  * array.
  *

include/libpmemobj++/make_persistent_array.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2019, Intel Corporation
+ * Copyright 2016-2020, Intel Corporation
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -194,6 +194,9 @@ make_persistent(allocation_flag flag = allocation_flag::none())
  * objects. Calls the objects' destructors before freeing memory.
  * This overload only participates in overload resolution if T is an array.
  *
+ * To ensure that proper recovery is possible, ptr should be set to null after
+ * delete_persistent call and within the same transaction.
+ *
  * @param[in,out] ptr persistent pointer to an array of objects.
  * @param[in] N the size of the array.
  *
@@ -238,6 +241,9 @@ delete_persistent(typename detail::pp_if_array<T>::type ptr, std::size_t N)
  * objects. Calls the objects' destructors before freeing memory.
  * This overload only participates in overload resolution if T is an array.
  *
+ * To ensure that proper recovery is possible, ptr should be set to null after
+ * delete_persistent call and within the same transaction.
+ *
  * @param[in,out] ptr persistent pointer to an array of objects.
  *
  * @throw transaction_scope_error if called outside of an active