Hide some internal stuff from Doxygen. Add/Improve the Doxygen

2005-12-16  Murray Cumming <murrayc@murrayc.com>

        * glib/glibmm/object.h:
        * glib/glibmm/objectbase.h: Hide some internal stuff
        from Doxygen. Add/Improve the Doxygen documentation.
        * glib/src/convert.hg: Correct the declaration of
        filename_display_name() to match the implementation.
        Previously this would have been unusable due to a linker
        error.

4 files changed, 63 insertions, 30 deletions

diff --git a/ChangeLog b/ChangeLog
index c019152c..33e6d238 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2005-12-16  Murray Cumming <murrayc@murrayc.com>
+
+	* glib/glibmm/object.h:
+	* glib/glibmm/objectbase.h: Hide some internal stuff 
+	from Doxygen. Add/Improve the Doxygen documentation.
+	* glib/src/convert.hg: Correct the declaration of 
+	filename_display_name() to match the implementation. 
+	Previously this would have been unusable due to a linker 
+	error.
+
 2005-11-30  Murray Cumming <murrayc@murrayc.com>
 
 	* docs/reference/Doxyfile.in: Define the @newin aliases, 
diff --git a/glib/glibmm/object.h b/glib/glibmm/object.h
index 3f196f9c..0335e92f 100644
--- a/glib/glibmm/object.h
+++ b/glib/glibmm/object.h
@@ -188,7 +188,7 @@ struct TypeTraits< Glib::RefPtr<T> >
   }
 };
 
-//This confuse the SUN Forte compiler, so we ifdef it out:
+//This confuses the SUN Forte compiler, so we ifdef it out:
 #ifdef GLIBMM_HAVE_DISAMBIGUOUS_CONST_TEMPLATE_SPECIALIZATIONS
 
 /** Partial specialization for pointers to const GObject instances.
diff --git a/glib/glibmm/objectbase.h b/glib/glibmm/objectbase.h
index bddfdcf6..137a7159 100644
--- a/glib/glibmm/objectbase.h
+++ b/glib/glibmm/objectbase.h
@@ -44,35 +44,44 @@ class GSigConnectionNode;
 
 //This inherits virtually from sigc::trackable so that people can multiply inherit glibmm classes from other sigc::trackable-derived classes.
 //See bugzilla.gnome.org bug # 116280
+/** Glib::ObjectBase is a common base class for Objects and Interfaces.
+ *
+ * This is used as virtual base class.  This means the ObjectBase
+ * constructor runs before all others, either implicitly or explicitly.  Each of
+ * the available constructors initializes custom_type_name_ in a different way.
+ */
 class ObjectBase : virtual public sigc::trackable
 {
 protected:
-  // Glib::ObjectBase is used as virtual base class.  This means the ObjectBase
-  // ctor runs before all others -- either implicitly or explicitly.  Each of
-  // the available ctors initializes custom_type_name_ in a different way:
-  //
-  // 1) default:      custom_type_name_ = "gtkmm__anonymous_custom_type"
-  // 2) const char*:  custom_type_name_ = custom_type_name
-  // 3) type_info:    custom_type_name_ = custom_type_info.name()
-  //
-  // All classes generated by gtkmmproc use ctor 2) with custom_type_name = 0,
-  // which essentially means it's not a custom type.  This is used to optimize
-  // vfunc and signal handler callbacks -- since the C++ virtual methods are
-  // not overridden, invocation can be skipped.
-  //
-  // The default ctor 1) is called implicitly from the ctor of user-derived
-  // classes -- yes, even if e.g. Gtk::Button calls ctor 2), a derived ctor
-  // always overrides this choice.  The language itself ensures that the ctor
-  // is only invoked once.
-  //
-  // Ctor 3) is a special feature to allow creation of derived types on the
-  // fly, without having to use g_object_new() manually.  This feature is
-  // sometimes necessary, e.g. to implement a custom Gtk::CellRenderer.  The
-  // neat trick with the virtual base class ctor makes it possible to reuse
-  // the same direct base class' ctor as with non-custom types.
-
+  /** This default constructor is called implicitly from the constructor of user-derived
+   * classes, even if, for instance, Gtk::Button calls a different ObjectBase constructor.
+   * This is normal behaviour for C++ virtual inheritance.
+   * 
+   * The GType name will be gtkmm__anonymous_custom_type.
+   */
   ObjectBase();
+
+  /** A derived constructor always overrides this choice.
+   * The C++ language itself ensures that the constructor
+   * is only invoked once.
+   * 
+   * All classes generated by gtkmmproc use this constructor, with custom_type_name = 0,
+   * which essentially means it's not a custom type.  This is used to optimize
+   * vfunc and signal handler callbacks -- since the C++ virtual methods are
+   * not overridden, invocation can be skipped.
+   *
+   * The GType name will be @a custom_type_name.
+   */
   explicit ObjectBase(const char* custom_type_name);
+
+  /** This constructor is a special feature to allow creation of derived types on the
+   * fly, without having to use g_object_new() manually.  This feature is
+   * sometimes necessary, e.g. to implement a custom Gtk::CellRenderer.  The
+   * neat trick with the virtual base class ctor makes it possible to reuse
+   * the same direct base class' constructor as with non-custom types.
+   *
+   * The GType name will be @a custom_type_info.name().
+   */
   explicit ObjectBase(const std::type_info& custom_type_info);
 
   virtual ~ObjectBase() = 0;
@@ -96,22 +105,33 @@ public:
   template <class PropertyType>
   void get_property(const Glib::ustring& property_name, PropertyType& value) const;
 
-  
-  virtual void reference()   const;
+  /** Increment the reference count for this object.
+   * You should never need to do this manually - use the object via a RefPtr instead.
+   */
+  virtual void reference() const;
+
+  /** Decrement the reference count for this object.
+   * You should never need to do this manually - use the object via a RefPtr instead.
+   */
   virtual void unreference() const;
 
+  ///Provides access to the underlying C GtkObject.
   inline GObject*       gobj()       { return gobject_; }
+
+  ///Provides access to the underlying C GtkObject.
   inline const GObject* gobj() const { return gobject_; }
 
-  // Give a ref-ed copy to someone. Use for direct struct access.
+  /// Give a ref-ed copy to someone. Use for direct struct access.
   GObject* gobj_copy() const;
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
   static ObjectBase* _get_current_wrapper(GObject* object);
   bool _cpp_destruction_is_in_progress() const;
-#endif
+#endif //DOXYGEN_SHOULD_SKIP_THIS
 
 protected:
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   GObject*            gobject_; // the GLib/GDK/GTK+ object instance
   const char*         custom_type_name_;
   bool                cpp_destruction_in_progress_;
@@ -123,13 +143,16 @@ protected:
   virtual void destroy_notify_();
 
   void _set_current_wrapper(GObject* object);
+#endif //DOXYGEN_SHOULD_SKIP_THIS
 
 private:
   // noncopyable
   ObjectBase(const ObjectBase&);
   ObjectBase& operator=(const ObjectBase&);
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   virtual void set_manage(); // calls g_error()
+#endif //DOXYGEN_SHOULD_SKIP_THIS
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
   friend class Glib::GSigConnectionNode; // for GSigConnectionNode::notify()
diff --git a/glib/src/convert.hg b/glib/src/convert.hg
index 2e89777d..8c206d26 100644
--- a/glib/src/convert.hg
+++ b/glib/src/convert.hg
@@ -261,7 +261,7 @@ Glib::ustring filename_display_basename(const std::string& filename);
  * @param filename: a pathname hopefully in the GLib file name encoding
  * @result A string containing a rendition of the filename in valid UTF-8.
  */
-Glib::ustring filename_display_name(const Glib::ustring& filename);
+Glib::ustring filename_display_name(const std::string& filename);
 
 /** @} group CharsetConv */