[glom] Documentation improvements for FieldFormatting and NumericFormatting

[David King <davidk src gnome org>]

commit 7e350d567d56b3a452f2302a4f9febaff240ef77
Author: David King <davidk openismus com>
Date:   Mon Jan 25 15:08:10 2010 +0100

    Documentation improvements for FieldFormatting and NumericFormatting
    
    * glom/libglom/data_structure/layout/fieldformatting.h:
    * glom/libglom/data_structure/numeric_format.h: Documentation
    improvements.

 .../data_structure/layout/fieldformatting.h        |   42 +++++++++++++++++---
 glom/libglom/data_structure/numeric_format.h       |   36 +++++++++++++----
 2 files changed, 64 insertions(+), 14 deletions(-)
---
diff --git a/glom/libglom/data_structure/layout/fieldformatting.h b/glom/libglom/data_structure/layout/fieldformatting.h
index a63585e..87ed2df 100644
--- a/glom/libglom/data_structure/layout/fieldformatting.h
+++ b/glom/libglom/data_structure/layout/fieldformatting.h
@@ -60,38 +60,68 @@ public:
   void get_choices(sharedptr<Relationship>& relationship_name, Glib::ustring& field, Glib::ustring& field_second) const;
   void set_choices(const sharedptr<Relationship>& relationship_name, const Glib::ustring& field, const Glib::ustring& field_second);
 
+  /** Get whether the text should be displayed with multiple lines in the
+   * details view. Text is displayed with a single line in the list view.
+   * @returns whether the text should be displayed with multiple lines
+   */
   bool get_text_format_multiline() const;
+  /** Set whether the text should be displayed with multiple lines in the
+   * details view. Text is displayed with a single line in the list view.
+   * @param[in] value whether the text should be displayed with multiple lines
+   */
   void set_text_format_multiline(bool value = true);
 
+  /** Get the number of lines of text that should be displayed.
+   * @see get_text_format_multiline()
+   * @returns the number of lines of text
+   */
   guint get_text_format_multiline_height_lines() const;
+
+  /** Get the number of lines of text that should be displayed.
+   * @returns the number of lines of text
+   */
   void set_text_format_multiline_height_lines(guint value);
 
-  /** The font name, as returned from Gtk::FontButton::get_font_name(), 
-   * which may include the size and style.
+  /** Set the font description, as returned from
+   * Gtk::FontButton::get_font_name(), which may include the size and style.
+   * @param font_desc a Pango font description string
    */
   void set_text_format_font(const Glib::ustring& font_desc);
 
-  /** The font name, as returned from Gtk::FontButton::get_font_name(), 
-   * which may include the size and style.
+  /** Get the font description, as returned from
+   * Gtk::FontButton::get_font_name(), which may include the size and style.
+   * @returns a Pango font description string
    */
   Glib::ustring get_text_format_font() const;
 
   /** Set the foreground color to use for text when displaying a field value.
+   * @param[in] color the text foreground color, in a format recognised by
+   * XParseColor
    */
   void set_text_format_color_foreground(const Glib::ustring& color);
 
   /** Get the foreground color to use for text for the specified value,
    * taking the negative-color into account, if specified.
+   * @returns the text foreground color, in a format recognised by XParseColor
    */
   Glib::ustring get_text_format_color_foreground_to_use(const Gnome::Gda::Value& value) const;
 
   /** Get the foreground color to use for text when displaying a field value.
-   * This should be overriden by by m_numeric_formatting.m_foreground_color_for_negatives
-   * if that is active.
+   * This should be overriden by
+   * m_numeric_formatting.m_foreground_color_for_negatives if that is active.
+   * @returns the text foreground color, in a format recognised by XParseColor
    */
   Glib::ustring get_text_format_color_foreground() const;
 
+  /** Set the background color to use for text when displaying a field value.
+   * @param[in] color a text background color, in a format recognised by
+   * XParseColor
+   */
   void set_text_format_color_background(const Glib::ustring& color);
+
+  /** Get the background color to use for text when displaying a field value.
+   * @returns the text background color, in a format recognised by XParseColor
+   */
   Glib::ustring get_text_format_color_background() const;
 
   enum HorizontalAlignment
diff --git a/glom/libglom/data_structure/numeric_format.h b/glom/libglom/data_structure/numeric_format.h
index 0d4bfa8..f54c0a8 100644
--- a/glom/libglom/data_structure/numeric_format.h
+++ b/glom/libglom/data_structure/numeric_format.h
@@ -39,23 +39,43 @@ public:
   bool operator==(const NumericFormat& src) const;
   bool operator!=(const NumericFormat& src) const;
   
-  /** The foreground color to use for negative values, 
-   * if m_alt_foreground_color_for_negatives is true.
+  /** The foreground color to use for negative values, if
+   * m_alt_foreground_color_for_negatives is true.
+   * @returns the foreground color, in a format recognised by XParseColor
    */
   static Glib::ustring get_alternative_color_for_negatives();
 
-  /** Get the number of decimal places we should allow to be shown until we
-    * show the awkward e syntax.  This should not be used if
-    * m_decimal_places_restricted is true.
-    */
+  /** Get the number of significant figures we should allow to be shown until
+   * we show the awkward e syntax. This should not be used if
+   * m_decimal_places_restricted is true.
+   * @returns the number of significant figures to show
+   */
   static guint get_default_precision();
 
+  /** String to use as the currency symbol. When the symbol is shown in the UI,
+   * a space is appended to the string, and the result is prepended to the
+   * data from the database. Be aware that the string supplied by the Glom
+   * document might have no representation in the current user's locale.
+   */
   Glib::ustring m_currency_symbol;
-  bool m_use_thousands_separator; //Setting this to false would override the locale, if it used a 1000s separator.
+
+  /** Setting this to false would override the locale, if it used a 1000s
+   * separator.
+   */
+  bool m_use_thousands_separator;
+
+  /** Whether to restrict numeric precision. If true, a fixed precision is set
+   * according to m_decimal_places. If false, the maximum precision is used.
+   * However, the chosen fixed precision might exceed the maximum precision.
+   */
   bool m_decimal_places_restricted;
+
+  /** The number of decimal places to show, although it is only used if
+   * m_decimal_places_restricted is false.
+   */
   guint m_decimal_places;
   
-  /// Whether to use an alernative foreground color for negative values.
+  /** Whether to use an alternative foreground color for negative values. */
   bool m_alt_foreground_color_for_negatives;
 };