[glibmm] Document Glib::Property and Glib::PropertyBase

[Murray Cumming <murrayc src gnome org>]

commit 2a0b37cb594ccb04c12cc21529014a45e65eb59d
Author: Mark Vender <markv743 yahoo co uk>
Date:   Sun Apr 1 11:29:34 2012 +0000

    Document Glib::Property and Glib::PropertyBase
    
    	* glib/glibmm/property.h:
    	Bug #673291

 ChangeLog              |    7 ++++
 glib/glibmm/property.h |   88 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 93 insertions(+), 2 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 34978e4..b2760ff 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2012-04-03  Mark Vender  <markv743 yahoo co uk>
+
+	Document Glib::Property and Glib::PropertyBase
+
+	* glib/glibmm/property.h:
+	Bug #673291
+
 2012-04-03  Murray Cumming  <murrayc murrayc com>
 
 	Slight rewrite of the documenation in the previous commit.
diff --git a/glib/glibmm/property.h b/glib/glibmm/property.h
index b3220b6..52f486d 100644
--- a/glib/glibmm/property.h
+++ b/glib/glibmm/property.h
@@ -48,11 +48,24 @@ void custom_set_property_callback(GObject* object, unsigned int property_id,
 
 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
-
+/**
+ * Base class for object properties
+ * 
+ * This class manages the value type-agnostic bits of object properties. 
+ */
 class PropertyBase
 {
 public:
+
+  /**
+   * Returns the name of the property
+   */
   Glib::ustring get_name() const;
+  
+  /**
+   * Notifies the object containing the property that the property has changed.
+   * In other words, emits "notify" signal with the property name.
+   */
   void notify();
 
 protected:
@@ -60,12 +73,28 @@ protected:
   Glib::ValueBase value_;
   GParamSpec*     param_spec_;
 
+  /**
+   * Constructs the property of type @a value_type for @a object. The property
+   * is not registered in the GObject object system, call install_property in
+   * order to do that. The properties are usually installed on the 
+   * initialization of the first instance of an object.
+   */
   PropertyBase(Glib::Object& object, GType value_type);
   ~PropertyBase();
 
+  /**
+   * Checks if the property has already been installed
+   */
   bool lookup_property(const Glib::ustring& name);
+  
+  /**
+   * Installs the property specified by the given @a param_spec.
+   */
   void install_property(GParamSpec* param_spec);
 
+  /**
+   * Returns the name of the property
+   */
   const char* get_name_internal() const;
 
 private:
@@ -84,7 +113,33 @@ private:
 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 };
 
-
+/**
+ * Represents an object property
+ * 
+ * This class maps one to one to a property of an object in GObject object 
+ * system. A property is a value associated to each instancy of a type and some
+ * global data for each property. The global data encompasses the following 
+ * information about the property:
+ *  * unique name, used to identify the property
+ *  * human-readable nick
+ *  * short explanation
+ *  * default value, minimum and maximum bounds (applicable depending on the 
+ *      type of the property)
+ *  * flags, defining, among other things, whether the property can be read or
+ *      written
+ * 
+ * The Property class currently supports only the name and default value. The
+ * minimum and maximum bounds are set to the full range of the value. The nick
+ * and the explanation are set to empty. The flags are set to indicate that the
+ * property can be both read from and written to.
+ * 
+ * The global information must be installed into the GObject system once per 
+ * property. This is handled automatically.
+ * 
+ * A property can be used only as direct data member of a type, inheriting from
+ * Glib::Object. A reference to the object must be passed on the construction of
+ * the property.
+ */
 template <class T>
 class Property : public PropertyBase
 {
@@ -92,15 +147,44 @@ public:
   typedef T PropertyType;
   typedef Glib::Value<T> ValueType;
 
+  /**
+   * Constructs a property of @a object with @a name. For each instance of the 
+   * object, the same property must be constructed with the same name
+   */
   Property(Glib::Object& object, const Glib::ustring& name);
+  
+  /**
+   * Constructs a property of @a object with @a name and @a default_value. For 
+   * each instance of the object, the same property must be constructed with the 
+   * same name
+   */
   Property(Glib::Object& object, const Glib::ustring& name, const PropertyType& default_value);
 
+  /**
+   * Sets the value of the property to @a data. The object containing the 
+   * property is notified about the change.
+   */
   inline void set_value(const PropertyType& data);
+  
+  /**
+   * Returns the value of the property
+   */
   inline PropertyType get_value() const;
 
+  /**
+   * Sets the value of the property to @a data. The object containing the 
+   * property is notified about the change.
+   */
   inline Property<T>& operator=(const PropertyType& data);
+  
+  /**
+   * Returs the value of the property
+   */
   inline operator PropertyType() const;
 
+  /**
+   * Returns a proxy object that can be used to manipulate this property
+   */
   inline Glib::PropertyProxy<T> get_proxy();
 };