RefPtr: Improve the reference docs now that this is a std::shared_ptr.

This should be simplified even more when we eventually remove,
or at least stop using, the RefPtr alias, using std::shared_ptr<>
in our API.

1 files changed, 13 insertions, 10 deletions

diff --git a/glib/glibmm/refptr.h b/glib/glibmm/refptr.h
index eee7f176..149f9a50 100644
--- a/glib/glibmm/refptr.h
+++ b/glib/glibmm/refptr.h
@@ -25,8 +25,7 @@
 namespace Glib
 {
 
-class ObjectBase;
-
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <class T_CppObject>
 void RefPtrDeleter(T_CppObject* object)
 {
@@ -35,6 +34,7 @@ void RefPtrDeleter(T_CppObject* object)
 
   object->unreference();
 }
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** RefPtr<> is a reference-counting shared smartpointer.
  *
@@ -42,8 +42,6 @@ void RefPtrDeleter(T_CppObject* object)
  * store. Consequently you cannot instantiate them yourself. Instead they
  * return a RefPtr which behaves much like an ordinary pointer in that members
  * can be reached with the usual <code>object_ptr->member</code> notation.
- * Unlike most other smart pointers, RefPtr doesn't support dereferencing
- * through <code>*object_ptr</code>.
  *
  * Reference counting means that a shared reference count is incremented each
  * time a RefPtr is copied, and decremented each time a RefPtr is destroyed,
@@ -51,18 +49,13 @@ void RefPtrDeleter(T_CppObject* object)
  * zero, the contained object is deleted, meaning  you don't need to remember
  * to delete the object.
  *
- * RefPtr<> can store any class that has reference() and unreference() methods,
- * and whose destructor is noexcept (the default for destructors).
- * In gtkmm, that is anything derived from Glib::ObjectBase, such as
- * Gdk::Pixmap.
- *
  * See the "Memory Management" section in the "Programming with gtkmm"
  * book for further information.
  */
 template <class T_CppObject>
 using RefPtr = std::shared_ptr<T_CppObject>;
 
-/** This would not be useful,
+/* This would not be useful,
  * because application code should not new these objects anyway.
  * And it is not useful inside glibmm or gtkmm code because
  * the constructors are protected, so can't be called from this utilility
@@ -76,6 +69,16 @@ make_refptr(T_Arg... arg)
 }
 */
 
+/** Create a RefPtr<> to an instance of any class that has reference() and
+ * unreference() methods, and whose destructor is noexcept (the default for destructors).
+ *
+ * In gtkmm, that is anything derived from Glib::ObjectBase, such as
+ * Gdk::Pixmap.
+ *
+ * Normal application code should not need to use this. However, this is necessary
+ * when implementing create() methods for derived Glib::ObjectBase-derived
+ * (not Gtk::Widget-derived) classes,  such as derived Gtk::TreeModels.
+ */
 template <class T_CppObject>
 RefPtr<T_CppObject>
 make_refptr_for_instance(T_CppObject* object)