0028854: The documentation should state where handle reference counting happens

The comment to class opencascade::handle<> in Standard_Handle.hxx now explains better the features differing it from std::shared_ptr<>.

src/Standard/Standard_Handle.hxx

@@ -35,16 +35,26 @@ namespace opencascade {
 
   //! Intrusive smart pointer for use with Standard_Transient class and its descendants.
   //!
-  //! This class is similar to boost::intrusive_ptr<>, with additional
+  //! This class is similar to boost::intrusive_ptr<>. The reference counter
-  //! feature historically supported by Handles in OCCT:
+  //! is part of the base class (Standard_Transient), thus creation of a handle
-  //! it has type conversion to const reference to handle to the base types,
+  //! does not require allocation of additional memory for the counter.
-  //! which allows it to be passed by reference
+  //! All handles to the same object share the common counter; object is deleted
-  //! in functions accepting reference to handle to base class.
+  //! when the last handle pointing on it is destroyed. It is safe to create a new
+  //! handle from plain C pointer to the object already pointed by another handle.
+  //! The same object can be referenced by handles of different types (as soon as 
+  //! they are compatible with the object type).
   //!
+  //! Handle has type cast operator to const reference to handle to the base
+  //! types, which allows it to be passed by reference in functions accepting 
+  //! reference to handle to base class, without copying.
+  //!
+  //! By default, the type cast operator is provided also for non-const reference.
   //! These casts (potentially unsafe) can be disabled by defining macro
   //! OCCT_HANDLE_NOCAST; if it is defined, generalized copy constructor
   //! and assignment operators are defined allowing to initialize handle
   //! of base type from handle to derived type.
+  //!
+  //! Weak pointers are not supported.
   template <class T>
   class handle
   {