[librsvgmm] Override documentation of most Handle methods

[Daniel Elstner <daniel src gnome org>]

commit cc5b7891b7ffb29d9200c63caed61aa360403a67
Author: Daniel Elstner <danielk openismus com>
Date:   Sun Sep 20 21:18:16 2009 +0200

    Override documentation of most Handle methods
    
    * librsvg/src/rsvg.hg (Rsvg::Handle): Override the inherited librsvg
    documentation of those methods where the description did not match the
    C++ API.  In particular, document the exceptions a method may throw.

 librsvg/src/rsvg.hg |   59 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 54 insertions(+), 5 deletions(-)
---
diff --git a/librsvg/src/rsvg.hg b/librsvg/src/rsvg.hg
index a659051..d887f27 100644
--- a/librsvg/src/rsvg.hg
+++ b/librsvg/src/rsvg.hg
@@ -91,7 +91,7 @@ class Handle : public Glib::Object
 {
   _CLASS_GOBJECT(Handle, RsvgHandle, RSVG_HANDLE, Glib::Object, GObject)
 #m4begin
-dnl // Don't wrap the get-pixbuf methods to avoid dragging in gtkmm as
+dnl // Don't wrap the get_pixbuf methods to avoid dragging gtkmm in as
 dnl // a dependency.  For basic SVG-to-Pixbuf rendering, the SVG pixbuf
 dnl // loader module can be used instead.
 #m4end
@@ -101,9 +101,25 @@ protected:
   _CTOR_DEFAULT()
 
 public:
+  /** Create an empty SVG handle.
+   * @return A pointer to the created SVG handle.
+   */
   _WRAP_CREATE()
+
+  /** Load an SVG from a memory buffer.
+   * @param data Pointer to the SVG data in memory.
+   * @param data_len Length of the SVG data in bytes.
+   * @return A pointer to the created SVG handle.
+   * @throw Rsvg::Error Thrown if the SVG could not be loaded.
+   */
   _WRAP_METHOD(static Glib::RefPtr<Handle> create_from_data(const guint8* data, gsize data_len),
                rsvg_handle_new_from_data, errthrow)
+
+  /** Load the SVG file specified by @a file_name.
+   * @param file_name The name of the file to load.
+   * @return A pointer to the created SVG handle.
+   * @throw Rsvg::Error Thrown if the SVG file could not be loaded.
+   */
   _WRAP_METHOD(static Glib::RefPtr<Handle> create_from_file(const std::string& file_name),
                rsvg_handle_new_from_file, errthrow)
 
@@ -113,32 +129,65 @@ public:
   /** Loads the next @a count bytes of the image.
    * If the data could not be loaded successfully, the loader will be closed,
    * and will not accept further writes.
-   * @param buf Pointer to SVG data
-   * @param count Size of the buffer in bytes
-   * @throw Rsvg::Error Thrown if the data could not be loaded successfully
+   * @param buf Pointer to SVG data.
+   * @param count Size of the buffer in bytes.
+   * @throw Rsvg::Error Thrown if the data could not be loaded successfully.
    */
   _WRAP_METHOD(void write(const guint8* buf, gsize count), rsvg_handle_write, errthrow)
 
   /** Closes the handle, to indicate that loading the image is complete.
-   * @throw Rsvg::Error Thrown if the loader could not close successfully
+   * @throw Rsvg::Error Thrown if the loader could not close successfully.
    */
   _WRAP_METHOD(void close(), rsvg_handle_close, errthrow)
 
   _WRAP_METHOD(Glib::ustring get_base_uri() const, rsvg_handle_get_base_uri)
   _WRAP_METHOD(void set_base_uri(const Glib::ustring& base_uri), rsvg_handle_set_base_uri)
 
+  /** Gets the size of the SVG.
+   * @param dimension_data Result object.
+   */
   _WRAP_METHOD(void get_dimensions(DimensionData& dimension_data) const,
                rsvg_handle_get_dimensions)
+
+  /** Gets the size of an SVG fragment.
+   * @param dimension_data Result object.
+   * @param id An element's ID within the SVG, or the empty string to get
+   *  the dimensions of the whole SVG. For example, if you have a layer
+   *  called <tt>"layer1"</tt> for that you want to get the dimensions,
+   *  pass <tt>"#layer1"</tt> as the ID.
+   * @return Whether the dimensions of element @a id could be retrieved.
+   */
   _WRAP_METHOD(bool get_dimensions_sub(DimensionData& dimension_data,
                                        const Glib::ustring& id) const,
                rsvg_handle_get_dimensions_sub)
+
+  /** Gets the position of an SVG fragment.
+   * @param position_data Result object.
+   * @param id An element's ID within the SVG. For example, if you have
+   *  a layer called <tt>"layer1"</tt> for that you want to get the position,
+   *  pass <tt>"#layer1"</tt> as the ID.
+   * @return Whether the position of element @a id could be retrieved.
+   */
   _WRAP_METHOD(bool get_position_sub(PositionData& position_data,
                                      const Glib::ustring& id) const,
                rsvg_handle_get_position_sub)
+
   _WRAP_METHOD(bool has_sub(const Glib::ustring& id) const, rsvg_handle_has_sub)
 
+  /** Draws an SVG to a cairo surface.
+   * @param cr A cairo context.
+   * @return Whether the SVG was drawn successfully.
+   */
   _WRAP_METHOD(bool render(const Cairo::RefPtr<Cairo::Context>& cr) const,
                rsvg_handle_render_cairo)
+
+  /** Draws an SVG fragment to a cairo surface.
+   * @param cr A cairo context.
+   * @param id An element's ID within the SVG, or the empty string to render
+   *  the whole SVG. For example, if you have a layer called <tt>"layer1"</tt>
+   *  that you wish to render, pass <tt>"#layer1"</tt> as the ID.
+   * @return Whether the @a id element was drawn successfully.
+   */
   _WRAP_METHOD(bool render_sub(const Cairo::RefPtr<Cairo::Context>& cr,
                                const Glib::ustring& id) const,
                rsvg_handle_render_cairo_sub)