[data_mutex] doc

README.md

@@ -26,6 +26,7 @@ In the list below each library shows its minimum supported C++ standard and has
 ---------|-------------
  [**atomic.hpp**](https://github.com/iboB/itlib/blob/master/include/itlib/atomic.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | Utility extensions for `<atomic>`.
  [**atomic_shared_ptr_storage.hpp**](https://github.com/iboB/itlib/blob/master/include/itlib/atomic_shared_ptr_storage.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A wrapper for `std::shared_ptr<T>` which allows atomic load, store and exchange. An alternative to C++20's `std::atomic<std::shared_ptr<T>>`.
+ [**data_mutex.hpp**](https://github.com/iboB/itlib/blob/master/include/itlib/data_mutex.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) [![Standard](https://img.shields.io/badge/C%2B%2B-17-red.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A template pair of an object and a mutex used to synchronize access to it. It makes it hard to cause bugs by forgetting to lock a mutex associated with an object. 
  [**dynamic_bitset.hpp**](https://github.com/iboB/itlib/blob/master/include/itlib/dynamic_bitset.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A class similar to `std::bitset`, but the number of bits is not a part of the type. It's also somewhat similar to `std::vector<bool>`, but (so far) it has more limited modification capabilities.
  [**expected.hpp**](https://github.com/iboB/itlib/blob/master/include/itlib/expected.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A union type of a value and an error. Similar to the [`std::expected`](https://en.cppreference.com/w/cpp/utility/expected) from C++23.
  [**flat_map.hpp**](https://github.com/iboB/itlib/blob/master/include/itlib/flat_map.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A class with the interface of `std::map` but implemented with an underlying `std::vector`-type container, thus providing better cache locality of the elements. Similar to [`boost::flat_map`](http://www.boost.org/doc/libs/1_61_0/doc/html/boost/container/flat_map.html) with the notable difference that the underlying container can be changed via a template argument.

include/itlib/data_mutex.hpp

@@ -34,6 +34,18 @@
 //                  DOCUMENTATION
 //
 // Simply include this file wherever you need.
+// The library defines the template type data_mutex<T, Mutex> which is a
+// pair of an object and an associated mutex used to synchronize access to it.
+//
+// To access the object inside one must use one of the following methods:
+// * unique_lock (mutex lock/unlock)
+// * try_unique_lock (mutex try_lock/unlock)
+// * shared_lock (mutex lock_shared/unlock_shared)
+// * try_shared_lock (mutex try_lock_shared/unlock_shared)
+//
+// They all return thin pointer-like wrappers of T. Which have operators
+// -> and *. In the case of the try_* functions, they also have a bool
+// interface
 //
 //
 //                  TESTS