[gtksourceviewmm] Documented SourceCompletionProvider.

[Krzesimir Nowak <krnowak src gnome org>]

commit 33631f92a36879bd71fc9ff9b8bf1a57f879ee4a
Author: Krzesimir Nowak <qdlacz gmail com>
Date:   Sun Jan 17 19:12:50 2010 +0100

    Documented SourceCompletionProvider.
    
    * gtksourceview/src/sourcecompletionprovider.hg: Documented.

 gtksourceview/src/sourcecompletionprovider.hg |  121 ++++++++++++++++++++++++-
 1 files changed, 119 insertions(+), 2 deletions(-)
---
diff --git a/gtksourceview/src/sourcecompletionprovider.hg b/gtksourceview/src/sourcecompletionprovider.hg
index d4dd419..045ff0b 100644
--- a/gtksourceview/src/sourcecompletionprovider.hg
+++ b/gtksourceview/src/sourcecompletionprovider.hg
@@ -20,9 +20,10 @@
 #include <glibmm/interface.h>
 #include <gtksourceview/gtksourcecompletionprovider.h>
 
+#include <gtksourceviewmm/sourcecompletionactivation.h>
 #include <gtksourceviewmm/sourcecompletioncontext.h>
-#include <gtksourceviewmm/sourcecompletionproposal.h>
 #include <gtksourceviewmm/sourcecompletioninfo.h>
+#include <gtksourceviewmm/sourcecompletionproposal.h>
 
 _DEFS(gtksourceviewmm,gtksourceview)
 _PINCLUDE(glibmm/private/interface_p.h)
@@ -31,33 +32,149 @@ namespace gtksourceview
 {
 
 class SourceCompletionContext;
-enum SourceCompletionActivation;
 
+/** Completion provider interface.
+ *
+ * You must implement this interface to provide proposals to SourceCompletion.
+ *
+ * @newin{2,10}
+ */
 class SourceCompletionProvider : public Glib::Interface
 {
   _CLASS_INTERFACE(SourceCompletionProvider, GtkSourceCompletionProvider, GTK_SOURCE_COMPLETION_PROVIDER, GtkSourceCompletionProviderIface)
 public:
   _WRAP_METHOD(Glib::ustring get_name() const, gtk_source_completion_provider_get_name)
 
+  /** Get the icon of the provider.
+   *
+   * @return The icon to be used for the provider, or empty Glib::RefPtr if the
+   * provider does not have a special icon.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::RefPtr<Gdk::Pixbuf> get_icon(), gtk_source_completion_provider_get_icon, refreturn)
+
+  /** Get the icon of the provider.
+   *
+   * @return The icon to be used for the provider, or empty Glib::RefPtr if the
+   * provider does not have a special icon.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Glib::RefPtr<const Gdk::Pixbuf> get_icon() const, gtk_source_completion_provider_get_icon, refreturn, constversion)
 
+  /** Populate @a context with proposals from a provider.
+   *
+   * @param context The SourceCompletionContext.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(void populate(const Glib::RefPtr<SourceCompletionContext>& context), gtk_source_completion_provider_populate)
 
+  /** Get whether the provider match the context of completion detailed in
+   *  @a context.
+   *
+   * @param context The SourceCompletionContext.
+   *
+   * @return @c true if provider matches the completion context, @c false
+   * otherwise.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(bool match(const Glib::RefPtr<const SourceCompletionContext>& context) const, gtk_source_completion_provider_match)
 
+  /** Get a customized info widget to show extra information of a proposal.
+   *
+   * This allows for customized widgets on a proposal basis, although in general
+   * providers will have the same custom widget for all their proposals and
+   * @a proposal can be ignored. The implementation of this function is
+   * optional. If implemented, update_info() @b must also be implemented. If not
+   * implemented, the default get_info() will be used to display extra
+   * information about a SourceCompletionProposal.
+   *
+   * @param proposal The currently selected SourceCompletionProposal.
+   *
+   * @return A custom Gtk::Widget to show extra information about @a proposal.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(Gtk::Widget* get_info_widget(const Glib::RefPtr<const SourceCompletionProposal>& proposal) const, gtk_source_completion_provider_get_info_widget)
 
+  /** Update extra information shown in @a info for @a proposal.
+   *
+   * This should be implemented if your provider sets a custom info widget for
+   * @a proposal. This function @b must be implemented when get_info_widget() is
+   * implemented.
+   *
+   * @param proposal A SourceCompletionProposal.
+   * @param info A SourceCompletionInfo.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(void update_info(const Glib::RefPtr<const SourceCompletionProposal>& proposal, const SourceCompletionInfo& info), gtk_source_completion_provider_update_info)
 
+  /** Get the Gtk::TextIter at which the completion for @a proposal starts.
+   *
+   * When implemented, the completion can use this information to position the
+   * completion window accordingly when a proposal is selected in the completion
+   * window.
+   *
+   * @param proposal A SourceCompletionProposal.
+   * @param context A SourceCompletionContext.
+   * @param iter A Gtk::TextIter.
+   *
+   * @return @c true if @a iter was set for @a proposal, @c false otherwise.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(bool get_start_iter(const Glib::RefPtr<const SourceCompletionContext>& context, const Glib::RefPtr<const SourceCompletionProposal>& proposal, Gtk::TextIter& iter), gtk_source_completion_provider_get_start_iter)
 
+  /** Activate @a proposal at @a iter.
+   *
+   * When this functions returns <tt>false</tt>, the default activation of
+   * @a proposal will take place which replaces the word at @a iter with the
+   * label of @a proposal.
+   *
+   * @param proposal A SourceCompletionProposal.
+   * @param iter A Gtk::TextIter.
+   *
+   * @return @c true to indicate that the proposal activation has been handled,
+   * @c false otherwise.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(bool activate_proposal(const Glib::RefPtr<SourceCompletionProposal>& proposal, const Gtk::TextIter& iter), gtk_source_completion_provider_activate_proposal)
 
+  /** Get with what kind of activation the provider should be activated.
+   *
+   * @return A combination of SourceCompletionActivation.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(SourceCompletionActivation get_activation() const, gtk_source_completion_provider_get_activation)
 
+  /** Get the delay in milliseconds before starting interactive completion for
+   *  this provider.
+   *
+   * A value of -1 indicates to use the default value as set
+   * by SourceCompletion::property_auto_complete_delay().
+   *
+   * @return The interactive delay in milliseconds.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(int get_interactive_delay() const, gtk_source_completion_provider_get_interactive_delay)
 
+  /** Get the provider priority.
+   *
+   * The priority determines the order in which proposals appear in the
+   * completion popup. Higher priorities are sorted before lower priorities. The
+   * default priority is 0.
+   *
+   * @return The provider priority.
+   *
+   * @newin{2,10}
+   */
   _WRAP_METHOD(int get_priority() const, gtk_source_completion_provider_get_priority)
 };