Glib::Property: Add some documentationglibmm-2-42

* glib/glibmm/propertyproxy.h:
* glib/glibmm/property.h: Move the documentation about registering
properties from PropertyProxy to Property, which is the class that registers
custom properties. Add a code snippet to the documentation. Bug #523043.

2 files changed, 31 insertions, 6 deletions

diff --git a/glib/glibmm/property.h b/glib/glibmm/property.h
index 3b2b422d..716d8599 100644
--- a/glib/glibmm/property.h
+++ b/glib/glibmm/property.h
@@ -137,6 +137,36 @@ private:
  * 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 to the constructor of
  * the property.
+ *
+ * You may register new properties for your class (actually for the underlying GType)
+ * simply by adding a Property instance as a class member.
+ * However, your constructor must call the Glib::ObjectBase constructor with a new GType name,
+ * in order to register a new GType.
+ *
+ * Example:
+ * @code
+ * class MyCellRenderer : public Gtk::CellRenderer
+ * {
+ * public:
+ *   MyCellRenderer()
+ *   :
+ *   Glib::ObjectBase (typeid(MyCellRenderer)),
+ *   Gtk::CellRenderer(),
+ *   property_mybool  (*this, "mybool", true),
+ *   property_myint_  (*this, "myint",    42)
+ *   {}
+ *
+ *   virtual ~MyCellRenderer() {}
+ *
+ *   // Glib::Property<> can be public,
+ *   Glib::Property<bool> property_mybool;
+ *   // or private, and combined with Glib::PropertyProxy<>.
+ *   Glib::PropertyProxy<int> property_myint() { return property_myint_.get_proxy(); }
+ *
+ * private:
+ *   Glib::Property<int> property_myint_;
+ * };
+ * @endcode
  */
 template <class T>
 class Property : public PropertyBase
@@ -146,7 +176,7 @@ public:
   typedef Glib::Value<T> ValueType;
 
   /**  Constructs a property of the @a object with the specified @a name.
-   * For each instance of the object, the same property must be constructed with the same 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);
 
diff --git a/glib/glibmm/propertyproxy.h b/glib/glibmm/propertyproxy.h
index a41f549a..56065038 100644
--- a/glib/glibmm/propertyproxy.h
+++ b/glib/glibmm/propertyproxy.h
@@ -38,11 +38,6 @@ namespace Glib
  * @endcode
  *
  * You may also receive notification when a property's value changes, by connecting to signal_changed().
- *
- * You may register new properties for your class (actually for the underlying GType)
- * simply by adding a PropertyProxy instance as a class member.
- * However, your constructor must call the Glib::ObjectBase constructor with a new GType name,
- * in order to register a new GType.
  */
 template <class T>
 class PropertyProxy : public PropertyProxy_Base