[glom] libglom: Some API documentation.

[Murray Cumming <murrayc src gnome org>]

commit 29e2053587968e56ff47ae68daad8c5c2af8432e
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu Jan 14 17:12:20 2010 +0100

    libglom: Some API documentation.
    
    * glom/libglom/data_structure/layout/layoutitem_field.h:
    * glom/libglom/data_structure/layout/usesrelationship.h:
    Added doxygen comments at request of Michael Hasselmann.

 ChangeLog                                          |    8 +++++
 .../data_structure/layout/layoutitem_field.h       |   21 ++++++++++++++
 .../data_structure/layout/usesrelationship.h       |   29 ++++++++++++++++++++
 3 files changed, 58 insertions(+), 0 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 7fc9943..528392e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2010-01-14  Murray Cumming  <murrayc murrayc com>
 
+	libglom: Some API documentation.
+
+	* glom/libglom/data_structure/layout/layoutitem_field.h:
+	* glom/libglom/data_structure/layout/usesrelationship.h:
+	Added doxygen comments at request of Michael Hasselmann.
+
+2010-01-14  Murray Cumming  <murrayc murrayc com>
+
 	Rename get_stringstream_precision_default().
 
 	* glom/libglom/data_structure/glomconversions.[h|cc]:
diff --git a/glom/libglom/data_structure/layout/layoutitem_field.h b/glom/libglom/data_structure/layout/layoutitem_field.h
index 3ce24a4..39fb6aa 100644
--- a/glom/libglom/data_structure/layout/layoutitem_field.h
+++ b/glom/libglom/data_structure/layout/layoutitem_field.h
@@ -56,6 +56,9 @@ private:
 };
 
 /** A LayoutItem that shows the data from a table field.
+ * The field may be in a known table, or in a to table of a relationship 
+ * or related relatinoship. See UsesRelationship::get_relationship() and 
+ * UsesRelationship::get_related_relationship() in the base class.
  */
 class LayoutItem_Field 
  : public LayoutItem,
@@ -72,9 +75,17 @@ public:
 
   bool operator==(const LayoutItem_Field& src) const;
 
+  /** Set the non-user-visible name of the field.
+   */
   virtual void set_name(const Glib::ustring& name);
+
+  /** Get the non-user-visible name of the field.
+   */
   virtual Glib::ustring get_name() const; //For use with our std::find_if() predicate.
 
+  /** Get the user-visible title for the field, in the user's current locale.
+   * This returns the name if no title is set.
+   */
   virtual Glib::ustring get_title_or_name() const;
 
   Glib::ustring get_title_or_name_no_custom() const;
@@ -115,9 +126,19 @@ public:
 
   FieldFormatting m_formatting;
 
+  /** Discover whether to use the default formatting for this field, 
+   * instead of some custom per-layout-item field formatting.
+   */
   bool get_formatting_use_default() const;
+
+  /** Specify whether to use the default formatting for this field, 
+   * instead of some custom per-layout-item field formatting.
+   */
   void set_formatting_use_default(bool use_default = true);
 
+  /** Get the field formatting used by this layout item, which 
+   * may be either custom field formatting or the default field formatting.
+   */
   const FieldFormatting& get_formatting_used() const;
 
   /** Compare the name, relationship, and related_relationship.
diff --git a/glom/libglom/data_structure/layout/usesrelationship.h b/glom/libglom/data_structure/layout/usesrelationship.h
index 4bedcde..c2c236a 100644
--- a/glom/libglom/data_structure/layout/usesrelationship.h
+++ b/glom/libglom/data_structure/layout/usesrelationship.h
@@ -56,10 +56,20 @@ public:
    */
   Glib::ustring get_related_relationship_name() const;
 
+  /** Return the relationship used by this item, if any, or a null sharedptr.
+   * See also get_has_relationship_name() which can prevent the need for your  
+   * own null sharedptr check.
+   */ 
   sharedptr<Relationship> get_relationship() const;
+
   void set_relationship(const sharedptr<Relationship>& relationship);
 
+  /** Return the related relationship used by this item, if any, or a null sharedptr.
+   * See also get_has_related_relationship_name() which can prevent the need for your  
+   * own null sharedptr check.
+   */ 
   sharedptr<Relationship> get_related_relationship() const;
+
   void set_related_relationship(const sharedptr<Relationship>& relationship);
 
   /** Returns either the @a parent_table, related to table, or doubly-related to-table.
@@ -68,23 +78,42 @@ public:
 
   /** Get the title of the relationship that is actually used,
    * falling back to the relationship's name.
+   * @param parent_table_title The title of table to which the item (or its relatinoships) belong.
    */
   Glib::ustring get_title_used(const Glib::ustring& parent_table_title) const;
   
   /** Get the singular title of the relationship that is actually used,
    * falling back to the regular (plural) title, and then to the relationship's name.
+   * @param parent_table_title The title of table to which the item (or its relatinoships) belong.
    */
   Glib::ustring get_title_singular_used(const Glib::ustring& parent_table_title) const;
 
   Glib::ustring get_to_field_used() const;
 
+  /** Get the name of the related relationship used, if any, or the relationship 
+   * if there is no related relationship, or an empty string if neither are 
+   * used by this item.
+   */ 
   Glib::ustring get_relationship_name_used() const;
 
+  /** Discover whether the relationship used allows the user to edit values 
+   * in its to table.
+   */
   bool get_relationship_used_allows_edit() const;
 
+  /** Get a name to use as an alias in SQL statements.
+   * This will always be the same string for items that have the same definition.
+   */ 
   Glib::ustring get_sql_join_alias_name() const;
+
+  /** Get a SQL fragment that defines the alias name as returned by 
+   * get_sql_join_alias_name().
+   */ 
   Glib::ustring get_sql_join_alias_definition() const;
 
+  /** Get the item's alias name, if it uses a relationship, or just get its table name.
+   * @param parent_table The table to which the item (or its relatinoships) belong.
+   */ 
   Glib::ustring get_sql_table_or_join_alias_name(const Glib::ustring& parent_table) const;
 
 private: