Improve documentation and GIR bindings.

git-svn-id: http://svn.drobilla.net/lad/trunk/ganv@3841 a436a847-0d15-0410-975c-d299462d15a1

11 files changed, 114 insertions, 91 deletions

diff --git a/ganv/canvas.h b/ganv/canvas.h
index 0770d2a..906f7c4 100644
--- a/ganv/canvas.h
+++ b/ganv/canvas.h
@@ -76,6 +76,10 @@ GanvCanvas* ganv_canvas_new(double width, double height);
 void
 ganv_canvas_resize(GanvCanvas* canvas, double width, double height);
 
+/**
+ * ganv_canvas_get_root:
+ * Return value: (transfer none): The root group of @canvas.
+ */
 GnomeCanvasGroup*
 ganv_canvas_get_root(const GanvCanvas* canvas);
 
diff --git a/ganv/edge.h b/ganv/edge.h
index 8e6c6cb..6fd2ffe 100644
--- a/ganv/edge.h
+++ b/ganv/edge.h
@@ -80,9 +80,17 @@ void
 ganv_edge_tick(GanvEdge* edge,
                double    seconds);
 
+/**
+ * ganv_edge_get_tail:
+ * Return value: (transfer none): The tail of @a edge.
+ */
 GanvNode*
 ganv_edge_get_tail(const GanvEdge* edge);
 
+/**
+ * ganv_edge_get_head:
+ * Return value: (transfer none): The head of @a edge.
+ */
 GanvNode*
 ganv_edge_get_head(const GanvEdge* edge);
 
diff --git a/ganv/module.h b/ganv/module.h
index f1c4f2c..718756b 100644
--- a/ganv/module.h
+++ b/ganv/module.h
@@ -54,6 +54,10 @@ ganv_module_new(GanvCanvas* canvas,
 guint
 ganv_module_num_ports(const GanvModule* module);
 
+/**
+ * ganv_module_get_port:
+ * Return value: (transfer none): The port on @module at @index.
+ */
 GanvPort*
 ganv_module_get_port(GanvModule* module,
                      guint       index);
diff --git a/ganv/node.h b/ganv/node.h
index 238492f..c814c8c 100644
--- a/ganv/node.h
+++ b/ganv/node.h
@@ -131,6 +131,10 @@ ganv_node_get_draw_properties(const GanvNode* node,
 
 const char* ganv_node_get_label(const GanvNode* node);
 
+/**
+ * ganv_node_get_partner:
+ * Return value: (transfer none): The partner of @node.
+ */
 GanvNode*
 ganv_node_get_partner(const GanvNode* node);
 
diff --git a/src/Canvas.cpp b/src/Canvas.cpp
index 692f3ee..f81c269 100644
--- a/src/Canvas.cpp
+++ b/src/Canvas.cpp
@@ -1824,8 +1824,8 @@ ganv_canvas_class_init(GanvCanvasClass* klass)
 	g_object_class_install_property(
 		gobject_class, PROP_WIDTH, g_param_spec_double(
 			"width",
-			_("width"),
-			_("width of the canvas"),
+			_("Width"),
+			_("The width of the canvas."),
 			0.0, G_MAXDOUBLE,
 			800.0,
 			(GParamFlags)G_PARAM_READWRITE));
@@ -1833,8 +1833,8 @@ ganv_canvas_class_init(GanvCanvasClass* klass)
 	g_object_class_install_property(
 		gobject_class, PROP_HEIGHT, g_param_spec_double(
 			"height",
-			_("height"),
-			_("height of the canvas"),
+			_("Height"),
+			_("The height of the canvas"),
 			0.0, G_MAXDOUBLE,
 			600.0,
 			(GParamFlags)G_PARAM_READWRITE));
@@ -1851,8 +1851,8 @@ ganv_canvas_class_init(GanvCanvasClass* klass)
 	g_object_class_install_property(
 		gobject_class, PROP_DIRECTION, g_param_spec_enum(
 			"direction",
-			_("direction"),
-			_("direction of the signal flow on the canvas"),
+			_("Direction"),
+			_("The direction of the signal flow on the canvas."),
 			dir_type,
 			GANV_DIRECTION_RIGHT,
 			(GParamFlags)G_PARAM_READWRITE));
@@ -1860,8 +1860,8 @@ ganv_canvas_class_init(GanvCanvasClass* klass)
 	g_object_class_install_property(
 		gobject_class, PROP_LOCKED, g_param_spec_boolean(
 			"locked",
-			_("locked"),
-			_("whether canvas items are movable"),
+			_("Locked"),
+			_("If true, nodes on the canvas can not be moved by the user."),
 			FALSE,
 			(GParamFlags)G_PARAM_READWRITE));
 
diff --git a/src/box.c b/src/box.c
index a6cdb85..0a70ef0 100644
--- a/src/box.c
+++ b/src/box.c
@@ -409,7 +409,7 @@ ganv_box_class_init(GanvBoxClass* class)
 		gobject_class, PROP_X1, g_param_spec_double(
 			"x1",
 			_("x1"),
-			_("top left x coordinate"),
+			_("Top left x coordinate."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -418,7 +418,7 @@ ganv_box_class_init(GanvBoxClass* class)
 		gobject_class, PROP_Y1, g_param_spec_double(
 			"y1",
 			_("y1"),
-			_("top left y coordinate"),
+			_("Top left y coordinate."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -427,7 +427,7 @@ ganv_box_class_init(GanvBoxClass* class)
 		gobject_class, PROP_X2, g_param_spec_double(
 			"x2",
 			_("x2"),
-			_("bottom right x coordinate"),
+			_("Bottom right x coordinate."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -436,7 +436,7 @@ ganv_box_class_init(GanvBoxClass* class)
 		gobject_class, PROP_Y2, g_param_spec_double(
 			"y2",
 			_("y2"),
-			_("bottom right y coordinate"),
+			_("Bottom right y coordinate."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -444,8 +444,8 @@ ganv_box_class_init(GanvBoxClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_RADIUS_TL, g_param_spec_double(
 			"radius-tl",
-			_("top left corner radius"),
-			_("top left corner radius"),
+			_("Top left radius"),
+			_("The radius of the top left corner."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -453,8 +453,8 @@ ganv_box_class_init(GanvBoxClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_RADIUS_TR, g_param_spec_double(
 			"radius-tr",
-			_("top right corner radius"),
-			_("top right corner radius"),
+			_("Top right radius"),
+			_("The radius of the top right corner."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -462,8 +462,8 @@ ganv_box_class_init(GanvBoxClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_RADIUS_BR, g_param_spec_double(
 			"radius-br",
-			_("bottom right corner radius"),
-			_("bottom right corner radius"),
+			_("Bottom right radius"),
+			_("The radius of the bottom right corner."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -471,8 +471,8 @@ ganv_box_class_init(GanvBoxClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_RADIUS_BL, g_param_spec_double(
 			"radius-bl",
-			_("bottom left corner radius"),
-			_("bottom left corner radius"),
+			_("Bottom left radius"),
+			_("The radius of the bottom left corner."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -480,8 +480,8 @@ ganv_box_class_init(GanvBoxClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_STACKED, g_param_spec_boolean(
 			"stacked",
-			_("stacked"),
-			_("Show the box with a stacked appearance."),
+			_("Stacked"),
+			_("Whether to show the box with a stacked appearance."),
 			FALSE,
 			G_PARAM_READWRITE));
 
diff --git a/src/circle.c b/src/circle.c
index 3c461c3..b27c822 100644
--- a/src/circle.c
+++ b/src/circle.c
@@ -337,8 +337,8 @@ ganv_circle_class_init(GanvCircleClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_RADIUS, g_param_spec_double(
 			"radius",
-			_("radius"),
-			_("radius of circle"),
+			_("Radius"),
+			_("The radius of the circle."),
 			0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
diff --git a/src/edge.c b/src/edge.c
index d2cbe5b..ae03200 100644
--- a/src/edge.c
+++ b/src/edge.c
@@ -476,24 +476,24 @@ ganv_edge_class_init(GanvEdgeClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_TAIL, g_param_spec_object(
 			"tail",
-			_("tail"),
-			_("node this edge starts from"),
+			_("Tail"),
+			_("Node this edge starts from."),
 			GANV_TYPE_NODE,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_HEAD, g_param_spec_object(
 			"head",
-			_("head"),
-			_("node this edge ends at"),
+			_("Head"),
+			_("Node this edge ends at."),
 			GANV_TYPE_NODE,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_WIDTH, g_param_spec_double(
 			"width",
-			_("line width"),
-			_("width of line in canvas units"),
+			_("Line width"),
+			_("Width of edge line."),
 			0.0, G_MAXDOUBLE,
 			2.0,
 			G_PARAM_READWRITE));
@@ -501,8 +501,8 @@ ganv_edge_class_init(GanvEdgeClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_HANDLE_RADIUS, g_param_spec_double(
 			"handle-radius",
-			_("handle radius"),
-			_("radius of handle in canvas units"),
+			_("Gandle radius"),
+			_("Radius of handle in canvas units."),
 			0.0, G_MAXDOUBLE,
 			4.0,
 			G_PARAM_READWRITE));
@@ -510,8 +510,8 @@ ganv_edge_class_init(GanvEdgeClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_DASH_LENGTH, g_param_spec_double(
 			"dash-length",
-			_("line dash length"),
-			_("length of dashes, or zero for no dashing"),
+			_("Line dash length"),
+			_("Length of line dashes, or zero for no dashing."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -519,8 +519,8 @@ ganv_edge_class_init(GanvEdgeClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_DASH_OFFSET, g_param_spec_double(
 			"dash-offset",
-			_("line dash offset"),
-			_("offset for dashes (useful for 'rubber band' animation)."),
+			_("Line dash offset"),
+			_("Start offset for line dashes, used for selected animation."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -528,8 +528,8 @@ ganv_edge_class_init(GanvEdgeClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_COLOR, g_param_spec_uint(
 			"color",
-			_("color"),
-			_("color as an RGBA integer"),
+			_("Color"),
+			_("Line color as an RGBA integer."),
 			0, G_MAXUINT,
 			0xA0A0A0FF,
 			G_PARAM_READWRITE));
@@ -537,40 +537,43 @@ ganv_edge_class_init(GanvEdgeClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_CURVED, g_param_spec_boolean(
 			"curved",
-			_("curved"),
-			_("whether line should be curved, not straight"),
+			_("Curved"),
+			_("Whether line should be curved rather than straight."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_ARROWHEAD, g_param_spec_boolean(
 			"arrowhead",
-			_("arrowhead"),
-			_("whether to show an arrowhead at the end point"),
+			_("Arrowhead"),
+			_("Whether to show an arrowhead at the head of this edge."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_SELECTED, g_param_spec_boolean(
 			"selected",
-			_("selected"),
-			_("whether this edge is selected"),
+			_("Selected"),
+			_("Whether this edge is selected."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_HIGHLIGHTED, g_param_spec_boolean(
 			"highlighted",
-			_("highlighted"),
-			_("whether to highlight the edge"),
+			_("Highlighted"),
+			_("Whether to highlight the edge."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_GHOST, g_param_spec_boolean(
 			"ghost",
-			_("ghost"),
-			_("whether to highlight the edge"),
+			_("Ghost"),
+			_("Whether this edge is a `ghost', which is an edge that is not "
+			  "added to the canvas data structures.  Ghost edges are used for "
+			  "temporary edges that are not considered `real', e.g. the edge "
+			  "made while dragging to make a connection."),
 			0,
 			G_PARAM_READWRITE));
 
diff --git a/src/node.c b/src/node.c
index 7d2c7b9..de7605e 100644
--- a/src/node.c
+++ b/src/node.c
@@ -457,37 +457,37 @@ ganv_node_class_init(GanvNodeClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_CANVAS, g_param_spec_object(
 			"canvas",
-			_("canvas"),
-			_("the canvas this node is on."),
+			_("Canvas"),
+			_("The canvas this node is on."),
 			GANV_TYPE_CANVAS,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_PARTNER, g_param_spec_object(
 			"partner",
-			_("partner"),
-			_("\
-Partners are nodes that should be visually aligned to correspond to each \
-other, even if they are not necessarily connected (e.g. for separate modules \
-representing the inputs and outputs of a single thing).  When the canvas is \
-arranged, the partner will be aligned as if there was an edge from this node \
-to its partner."),
+			_("Partner"),
+			_("Partners are nodes that should be visually aligned to correspond"
+			  " to each other, even if they are not necessarily connected (e.g."
+			  " for separate modules representing the inputs and outputs of a"
+			  " single thing).  When the canvas is arranged, the partner will"
+			  " be aligned as if there was an edge from this node to its"
+			  " partner."),
 			GANV_TYPE_NODE,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_LABEL, g_param_spec_string(
 			"label",
-			_("label"),
-			_("the text to display"),
+			_("Label"),
+			_("The text to display as a label on this node."),
 			NULL,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_DASH_LENGTH, g_param_spec_double(
 			"dash-length",
-			_("border dash length"),
-			_("length of dashes, or zero for no dashing"),
+			_("Border dash length"),
+			_("Length of border dashes, or zero for no dashing."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -495,8 +495,8 @@ to its partner."),
 	g_object_class_install_property(
 		gobject_class, PROP_DASH_OFFSET, g_param_spec_double(
 			"dash-offset",
-			_("border dash offset"),
-			_("offset for dashes (useful for 'rubber band' animation)."),
+			_("Border dash offset"),
+			_("Start offset for border dashes, used for selected animation."),
 			0.0, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -504,8 +504,8 @@ to its partner."),
 	g_object_class_install_property(
 		gobject_class, PROP_BORDER_WIDTH, g_param_spec_double(
 			"border-width",
-			_("border width"),
-			_("width of the border around this node."),
+			_("Border width"),
+			_("Width of the border line."),
 			0.0, G_MAXDOUBLE,
 			2.0,
 			G_PARAM_READWRITE));
@@ -513,8 +513,8 @@ to its partner."),
 	g_object_class_install_property(
 		gobject_class, PROP_FILL_COLOR, g_param_spec_uint(
 			"fill-color",
-			_("fill color"),
-			_("color of internal area"),
+			_("Fill color"),
+			_("Color of internal area."),
 			0, G_MAXUINT,
 			DEFAULT_FILL_COLOR,
 			G_PARAM_READWRITE));
@@ -522,8 +522,8 @@ to its partner."),
 	g_object_class_install_property(
 		gobject_class, PROP_BORDER_COLOR, g_param_spec_uint(
 			"border-color",
-			_("border color"),
-			_("color of border area"),
+			_("Border color"),
+			_("Color of border line."),
 			0, G_MAXUINT,
 			DEFAULT_BORDER_COLOR,
 			G_PARAM_READWRITE));
@@ -531,40 +531,40 @@ to its partner."),
 	g_object_class_install_property(
 		gobject_class, PROP_CAN_TAIL, g_param_spec_boolean(
 			"can-tail",
-			_("can tail"),
-			_("whether this object can be the tail of an edge"),
+			_("Can tail"),
+			_("Whether this node can be the tail of an edge."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_CAN_HEAD, g_param_spec_boolean(
 			"can-head",
-			_("can head"),
-			_("whether this object can be the head of an edge"),
+			_("Can head"),
+			_("Whether this object can be the head of an edge."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_SELECTED, g_param_spec_boolean(
 			"selected",
-			_("selected"),
-			_("whether this object is selected"),
+			_("Selected"),
+			_("Whether this object is selected."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_HIGHLIGHTED, g_param_spec_boolean(
 			"highlighted",
-			_("highlighted"),
-			_("whether this object is highlighted"),
+			_("Highlighted"),
+			_("Whether this object is highlighted."),
 			0,
 			G_PARAM_READWRITE));
 
 	g_object_class_install_property(
 		gobject_class, PROP_DRAGGABLE, g_param_spec_boolean(
 			"draggable",
-			_("draggable"),
-			_("whether this object is draggable"),
+			_("Draggable"),
+			_("Whether this object is draggable."),
 			0,
 			G_PARAM_READWRITE));
 
diff --git a/src/port.c b/src/port.c
index 63efd2e..7a80e54 100644
--- a/src/port.c
+++ b/src/port.c
@@ -229,8 +229,8 @@ ganv_port_class_init(GanvPortClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_IS_INPUT, g_param_spec_boolean(
 			"is-input",
-			_("is input"),
-			_("whether this port is an input (or an output, if false)"),
+			_("Is input"),
+			_("Whether this port is an input, rather than an output."),
 			0,
 			G_PARAM_READWRITE));
 
diff --git a/src/text.c b/src/text.c
index 0a616d2..cb360b8 100644
--- a/src/text.c
+++ b/src/text.c
@@ -334,8 +334,8 @@ ganv_text_class_init(GanvTextClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_TEXT, g_param_spec_string(
 			"text",
-			_("text"),
-			_("the text to display"),
+			_("Text"),
+			_("The string to display."),
 			NULL,
 			G_PARAM_READWRITE));
 
@@ -343,7 +343,7 @@ ganv_text_class_init(GanvTextClass* class)
 		gobject_class, PROP_X, g_param_spec_double(
 			"x",
 			_("x"),
-			_("x coordinate"),
+			_("Top left x coordinate."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -352,7 +352,7 @@ ganv_text_class_init(GanvTextClass* class)
 		gobject_class, PROP_Y, g_param_spec_double(
 			"y",
 			_("y"),
-			_("y coordinate"),
+			_("Top left y coordinate."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			0.0,
 			G_PARAM_READWRITE));
@@ -360,8 +360,8 @@ ganv_text_class_init(GanvTextClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_WIDTH, g_param_spec_double(
 			"width",
-			_("width"),
-			_("width"),
+			_("Width"),
+			_("The current width of the text."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			1.0,
 			G_PARAM_READWRITE));
@@ -369,8 +369,8 @@ ganv_text_class_init(GanvTextClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_HEIGHT, g_param_spec_double(
 			"height",
-			_("height"),
-			_("height"),
+			_("Height"),
+			_("The current height of the text."),
 			-G_MAXDOUBLE, G_MAXDOUBLE,
 			1.0,
 			G_PARAM_READWRITE));
@@ -378,8 +378,8 @@ ganv_text_class_init(GanvTextClass* class)
 	g_object_class_install_property(
 		gobject_class, PROP_COLOR, g_param_spec_uint(
 			"color",
-			_("color"),
-			_("the color of the text"),
+			_("Color"),
+			_("The color of the text."),
 			0, G_MAXUINT,
 			DEFAULT_TEXT_COLOR,
 			G_PARAM_READWRITE));