From 3b9f400868fc382a5f61db4eb7105be999049c7b Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Fri, 9 Dec 2011 00:36:44 +0000
Subject: Improve documentation.

git-svn-id: http://svn.drobilla.net/lad/trunk/ganv@3840 a436a847-0d15-0410-975c-d299462d15a1
---
 ganv/box.h    | 14 ++++++++++++--
 ganv/canvas.h | 22 ++++++++++++++++++++++
 ganv/circle.h |  6 ++++++
 ganv/module.h |  2 ++
 ganv/node.h   | 19 +++++++++++--------
 ganv/port.h   |  4 +++-
 6 files changed, 56 insertions(+), 11 deletions(-)

(limited to 'ganv')

diff --git a/ganv/box.h b/ganv/box.h
index 84fcb8a..f97788f 100644
--- a/ganv/box.h
+++ b/ganv/box.h
@@ -36,6 +36,11 @@ struct _GanvBox
 	GanvBoxImpl* impl;
 };
 
+/**
+ * GanvBoxClass:
+ * @set_width: Set the width of the box.
+ * @set_height: Set the height of the box.
+ */
 struct _GanvBoxClass {
 	GanvNodeClass parent_class;
 
@@ -57,8 +62,13 @@ double ganv_box_get_height(const GanvBox* box);
 void   ganv_box_set_height(GanvBox* box, double height);
 double ganv_box_get_border_width(const GanvBox* box);
 
-void
-ganv_box_normalize(GanvBox* box);
+/**
+ * ganv_box_normalize:
+ * @box: The box to normalize.
+ *
+ * Normalize the box coordinates such that x1 < x2 and y1 < y2.
+ */
+void ganv_box_normalize(GanvBox* box);
 
 G_END_DECLS
 
diff --git a/ganv/canvas.h b/ganv/canvas.h
index a011cff..0770d2a 100644
--- a/ganv/canvas.h
+++ b/ganv/canvas.h
@@ -16,6 +16,14 @@
 #ifndef GANV_CANVAS_H
 #define GANV_CANVAS_H
 
+/**
+ * SECTION:ganv
+ * 
+ * @version: 1.0.0
+ * @Version: 1.0.0
+ *
+ * #GanvCanvas is possibly the greatest thing, ever.
+ */
 #include <libgnomecanvas/libgnomecanvas.h>
 
 #include "ganv/types.h"
@@ -34,6 +42,14 @@ struct GanvCanvasImpl;
 
 typedef struct _GanvCanvasClass GanvCanvasClass;
 
+/**
+ * GanvDirection:
+ * @GANV_DIRECTION_DOWN: Signal flows from top to bottom.
+ * @GANV_DIRECTION_RIGHT: Signal flows from left to right.
+ *
+ * Specifies the direction of signal flow on the canvas, which affects the
+ * appearance of modules and how the canvas is auto-arranged.
+ */
 typedef enum {
 	GANV_DIRECTION_DOWN,
 	GANV_DIRECTION_RIGHT
@@ -85,6 +101,8 @@ typedef void (*GanvEdgeFunction)(GanvEdge* edge);
 
 /**
  * ganv_canvas_for_each_edge_from:
+ * @canvas: The canvas.
+ * @tail: The tail to enumerate every edge for.
  * @f: (scope call): A function to call on every edge leaving @tail.
  */
 void
@@ -94,6 +112,8 @@ ganv_canvas_for_each_edge_from(GanvCanvas*      canvas,
 
 /**
  * ganv_canvas_for_each_edge_to:
+ * @canvas: The canvas.
+ * @head: The head to enumerate every edge for.
  * @f: (scope call): A function to call on every edge entering @head.
  */
 void
@@ -103,6 +123,8 @@ ganv_canvas_for_each_edge_to(GanvCanvas*      canvas,
 
 /**
  * ganv_canvas_for_each_edge_on:
+ * @canvas: The canvas.
+ * @node: The node to enumerate every edge for.
  * @f: (scope call): A function to call on every edge attached to @node.
  */
 void
diff --git a/ganv/circle.h b/ganv/circle.h
index b55fb44..8347525 100644
--- a/ganv/circle.h
+++ b/ganv/circle.h
@@ -31,6 +31,12 @@ typedef struct _GanvCircle      GanvCircle;
 typedef struct _GanvCircleClass GanvCircleClass;
 typedef struct _GanvCircleImpl  GanvCircleImpl;
 
+/**
+ * GanvCircle:
+ *
+ * A circular #GanvNode.  A #GanvCircle is a leaf, that is, it does not contain
+ * any child nodes (though, like any #GanvNode, it may have a label).
+ */
 struct _GanvCircle
 {
 	GanvNode        node;
diff --git a/ganv/module.h b/ganv/module.h
index 4f8014d..f1c4f2c 100644
--- a/ganv/module.h
+++ b/ganv/module.h
@@ -78,7 +78,9 @@ ganv_module_embed(GanvModule* module,
 
 /**
  * ganv_module_for_each_port:
+ * @module: The module.
  * @f: (scope call): A function to call on every port on @module.
+ * @data: User data to pass to @f.
  */
 void
 ganv_module_for_each_port(GanvModule*      module,
diff --git a/ganv/node.h b/ganv/node.h
index fb093cd..238492f 100644
--- a/ganv/node.h
+++ b/ganv/node.h
@@ -117,14 +117,17 @@ ganv_node_head_vector(const GanvNode* self,
                       double*         y2);
 
 /**
-   Get the colours that should currently be used for drawing this node.
-   Note these may not be identical to the property values because of
-   highlighting and selection.
-*/
-void ganv_node_get_draw_properties(const GanvNode* node,
-                                   double*         dash_length,
-                                   double*         border_color,
-                                   double*         fill_color);
+ * ganv_node_get_draw_properties:
+ *
+ * Get the colours that should currently be used for drawing this node.  Note
+ * these may not be identical to the property values because of highlighting
+ * and selection.
+ */
+void
+ganv_node_get_draw_properties(const GanvNode* node,
+                              double*         dash_length,
+                              double*         border_color,
+                              double*         fill_color);
 
 const char* ganv_node_get_label(const GanvNode* node);
 
diff --git a/ganv/port.h b/ganv/port.h
index 8c3de24..5052012 100644
--- a/ganv/port.h
+++ b/ganv/port.h
@@ -76,7 +76,9 @@ ganv_port_get_natural_width(const GanvPort* port);
 
 /**
  * ganv_port_get_module:
- * Return value: (transfer none): The module @a port is on.
+ * @port: The port.
+ *
+ * Return value: (transfer none): The module @port is on.
  */
 GanvModule* ganv_port_get_module(const GanvPort* port);
 
-- 
cgit v1.2.1