[gtksourceviewmm] Documented SourceCompletionProposal.

[Krzesimir Nowak <krnowak src gnome org>]

commit e1e089f58df2cdf93f4ce0d8950f9a9ba94e6cf9
Author: Krzesimir Nowak <qdlacz gmail com>
Date:   Sun Jan 17 19:12:11 2010 +0100

    Documented SourceCompletionProposal.
    
    * gtksourceview/src/sourcecompletionproposal.hg: Documented.

 gtksourceview/src/sourcecompletionproposal.hg |   97 +++++++++++++++++++++++++
 1 files changed, 97 insertions(+), 0 deletions(-)
---
diff --git a/gtksourceview/src/sourcecompletionproposal.hg b/gtksourceview/src/sourcecompletionproposal.hg
index 8eff078..4969e6f 100644
--- a/gtksourceview/src/sourcecompletionproposal.hg
+++ b/gtksourceview/src/sourcecompletionproposal.hg
@@ -28,21 +28,118 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace gtksourceview
 {
 
+/** Completion proposal object.
+ *
+ * The proposal interface represents a completion item in the completion window.
+ * It provides information on how to display the completion item and what action
+ * should be taken when the completion item is activated.
+ *
+ * @newin{2,10}
+ */
 class SourceCompletionProposal : public Glib::Interface
 {
   _CLASS_INTERFACE(SourceCompletionProposal, GtkSourceCompletionProposal, GTK_SOURCE_COMPLETION_PROPOSAL, GtkSourceCompletionProposalIface)
 
 public:
+  /** Gets the label of a proposal.
+   *
+   * The label is shown in the list of proposals as plain text. If you need any
+   * markup (such as bold or italic text), you have to implement get_markup().
+   *
+   * @return The label of a proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::ustring get_label() const, gtk_source_completion_proposal_get_label)
+
+  /** Gets the label of a proposal with markup. The label is shown in the list
+   * of proposals and may contain markup. This will be used instead of
+   * get_label() if implemented.
+   *
+   * @return The label of a proposal with markup.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::ustring get_markup() const, gtk_source_completion_proposal_get_markup)
+
+  /** Gets the text of a proposal.
+   *
+   * The text that is inserted into the text buffer when the proposal is
+   * activated by the default activation. You are free to implement a custom
+   * activation handler in the provider and not implement this function.
+   *
+   * @return The text of a proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::ustring get_text() const, gtk_source_completion_proposal_get_text)
+
+  /** Gets the icon of a proposal.
+   *
+   * @return The icon of a proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::RefPtr<Gdk::Pixbuf> get_icon(), gtk_source_completion_proposal_get_icon, refreturn)
+
+  /** Gets the icon of a proposal.
+   *
+   * @return The icon of a proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::RefPtr<const Gdk::Pixbuf> get_icon() const, gtk_source_completion_proposal_get_icon, constversion, refreturn)
+
+  /** Gets extra information associated to the proposal.
+   *
+   * This information will be used to present the user with extra, detailed
+   * information about the selected proposal.
+   *
+   * @return The extra information of a proposal or empty string if no extra
+   * information is associated to a proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::ustring get_info() const, gtk_source_completion_proposal_get_info)
+
+  /** Emits the "changed" signal on a proposal.
+   *
+   * This should be called by implementations whenever the name, icon or info of
+   * the proposal has changed.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(void changed(), gtk_source_completion_proposal_changed)
+
+  /** Get the hash value of a proposal.
+   *
+   * This is used to (together with equal()) to match proposals in the
+   * completion model. By default, it uses a direct hash.
+   *
+   * @return The hash value of a proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(guint hash() const, gtk_source_completion_proposal_hash)
+
+  /** Get whether two proposal objects are the same.
+   *
+   * This is used to (together with hash()) to match proposals in the
+   * completion model. By default, it uses direct equality.
+   *
+   * @param other A SourceCompletionProposal.
+   * @return @c true if a proposal and @a other are the same proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(bool equal(const Glib::RefPtr<const SourceCompletionProposal>& other) const, gtk_source_completion_proposal_equal)
 
+  /** Emitted when the proposal has changed.
+   *
+   * The completion popup will react to this by updating the shown information.
+   *
+   * @newin{2,10}
+   */
   _WRAP_SIGNAL(void changed(), "changed")
 };