doc: update annotations for functions, properties, and signals

This commit improves annotations for them.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>

7 files changed, 53 insertions, 55 deletions

diff --git a/doc/overview.md b/doc/overview.md
index 7c19b8a..8ff9628 100644
--- a/doc/overview.md
+++ b/doc/overview.md
@@ -1,7 +1,7 @@
 Title: Overview
 
 This library gives some objects for abstraction to operate system resources in Linux FireWire
-subsystem. This library mainly supports operations for asynchronous communication to nodes on
+subsystem. This library mainly supports operations for asynchronous communication with nodes in
 IEEE 1394 bus.
 
 This library originally supported some model-specific operations for Audio and Music units on
diff --git a/src/fw_fcp.c b/src/fw_fcp.c
index ef2b7a3..967fb74 100644
--- a/src/fw_fcp.c
+++ b/src/fw_fcp.c
@@ -10,12 +10,13 @@
  * HinawaFwFcp:
  * A FCP transaction executor to node in IEEE 1394 bus.
  *
- * A HinawaFwFcp supports Function Control Protocol (FCP) in IEC 61883-1, in which no way is defined
- * to match response against command by the contents of frames. In 'AV/C Digital Interface Command
- * Set General Specification Version 4.2' (Sep 1 2004, 1394TA), a pair of command and response is
- * loosely matched by the contents of frames.
+ * [class@FwFcp] supports Function Control Protocol (FCP) in IEC 61883-1. FCP transaction consists
+ * of a pair of asynchronous transactions for command and response, while the protocol has no
+ * mechanism to match them. In AV/C Digital Interface Command Set General Specification Version 4.2
+ * (Sep 1 2004, 1394TA), they are loosely matched by the content of their frames, and this class
+ * employs the way.
  *
- * Any of transaction frames should be aligned to 8bit (byte). This class is an application of
+ * Any of transaction frames should be aligned to 8 bit (1 byte). This class is an application of
  * [class@FwReq] / [class@FwResp].
  */
 
@@ -365,10 +366,10 @@ static void handle_responded_signal(HinawaFwFcp *self, guint generation, guint t
  * @error: A [struct@GLib.Error]. Error can be generated with four domains; Hinawa.FwNodeError,
  *	   Hinawa.FwReqError, and Hinawa.FwFcpError.
  *
- * Finish the pair of asynchronous transaction for AV/C command and response transactions. The
- * timeout_ms parameter is used to wait for response transaction since the command transaction is
- * initiated. The timeout is not expanded in the case that AV/C INTERIM status arrived, thus the
- * caller should expand the timeout in advance for the case.
+ * Finish the pair of asynchronous transaction for AV/C command and response. The @timeout_ms
+ * parameter is used to wait for response transaction since the command transaction is initiated.
+ * The timeout is not expanded in the case that AV/C INTERIM status arrived, thus the caller should
+ * expand the timeout in advance for the case.
  *
  * Returns: TRUE if the overall operation finishes successfully, otherwise FALSE.
  * Since: 2.6
@@ -490,10 +491,10 @@ end:
  * @error: A [struct@GLib.Error]. Error can be generated with four domains; Hinawa.FwNodeError,
  *	   Hinawa.FwReqError, and Hinawa.FwFcpError.
  *
- * Finish the pair of asynchronous transaction for AV/C command and response transactions. The
- * timeout_ms parameter is used to wait for response transaction since the command transaction is
- * initiated The timeout is not expanded in the case that AV/C INTERIM status arrived, thus the
- * caller should expand the timeout in advance for the case.
+ * Finish the pair of asynchronous transaction for AV/C command and response. The @timeout_ms
+ * parameter is used to wait for response transaction since the command transaction is initiated.
+ * The timeout is not expanded in the case that AV/C INTERIM status arrived, thus the caller should
+ * expand the timeout in advance for the case.
  *
  * Returns: TRUE if the overall operation finishes successfully, otherwise FALSE.
  *
diff --git a/src/fw_fcp.h b/src/fw_fcp.h
index f767b97..d21592e 100644
--- a/src/fw_fcp.h
+++ b/src/fw_fcp.h
@@ -21,10 +21,10 @@ struct _HinawaFwFcpClass {
 	 * HinawaFwFcpClass::responded:
 	 * @self: A [class@FwFcp].
 	 * @generation: The generation of bus topology.
-	 * @tstamp: The time stamp at which the request arrived for the response for FCP
+	 * @tstamp: The time stamp at which the request subaction arrived for the response of FCP
 	 *	    transaction.
 	 * @frame: (array length=frame_size)(element-type guint8): The array with elements for byte
-	 *	   data of response for Function Control Protocol.
+	 *	   data in the response of Function Control Protocol.
 	 * @frame_size: The number of elements of the array.
 	 *
 	 * Class closure for the [signal@FwFcp::responded] signal.
diff --git a/src/fw_node.c b/src/fw_node.c
index dd71079..f7de24a 100644
--- a/src/fw_node.c
+++ b/src/fw_node.c
@@ -10,11 +10,10 @@
 
 /**
  * HinawaFwNode:
- * An event listener for FireWire node
+ * An event listener for node in IEEE 1394 bus.
  *
- * A [class@FwNode] is an event listener for a specified node on IEEE 1394 bus. This class is an
- * application of Linux FireWire subsystem. All of operations utilize ioctl(2) with subsystem
- * specific request commands.
+ * [class@FwNode] listens to any events for an associated node in IEEE 1394 bus. Additionally,
+ * it provides some methods to retrieve fundamental information about the bus.
  *
  * Since: 1.4
  */
@@ -216,7 +215,7 @@ static void hinawa_fw_node_class_init(HinawaFwNodeClass *klass)
 	/**
 	 * HinawaFwNode:root-node-id:
 	 *
-	 * Node ID of root node in bus topology at current generation of the bus topology.
+	 * Node ID of root node in bus topology at current generation of bus topology.
 	 *
 	 * Since: 1.4
 	 */
@@ -243,7 +242,7 @@ static void hinawa_fw_node_class_init(HinawaFwNodeClass *klass)
 	/**
 	 * HinawaFwNode:card-id:
 	 *
-	 * The numeric index for 1394 OHCI hardware used for the communication to the node. The
+	 * The numeric index for 1394 OHCI hardware used for the communication with the node. The
 	 * value is stable against bus generation.
 	 *
 	 * Since: 3.0
@@ -251,7 +250,7 @@ static void hinawa_fw_node_class_init(HinawaFwNodeClass *klass)
 	fw_node_props[FW_NODE_PROP_TYPE_CARD_ID] =
 		g_param_spec_uint("card-id", "card-id",
 				  "The numeric index for 1394 OHCI hardware used for the "
-				  "communication to the node",
+				  "communication with the node",
 				  0, G_MAXUINT32, 0,
 				  G_PARAM_READABLE);
 
@@ -281,8 +280,8 @@ static void hinawa_fw_node_class_init(HinawaFwNodeClass *klass)
 	 * HinawaFwNode::disconnected:
 	 * @self: A [class@FwNode].
 	 *
-	 * Emitted when the node is not available anymore due to removal from IEEE 1394 bus. It's
-	 * preferable to call [method@GObject.Object.unref] immediately to release file descriptor.
+	 * Emitted when the node is not available anymore in Linux system. It's preferable to call
+	 * [method@GObject.Object.unref] immediately to release file descriptor.
 	 *
 	 * Since: 1.4
 	 */
@@ -359,7 +358,7 @@ static int update_info(HinawaFwNode *self)
  * @error: A [struct@GLib.Error]. Error can be generated with two domains; GLib.Error and
  *	   Hinawa.FwNodeError.
  *
- * Open Linux FireWire character device to operate node on IEEE 1394 bus.
+ * Open Linux FireWire character device to operate node in IEEE 1394 bus.
  *
  * Returns: TRUE if the overall operation finishes successfully, otherwise FALSE.
  *
@@ -417,7 +416,7 @@ gboolean hinawa_fw_node_open(HinawaFwNode *self, const gchar *path, gint open_fl
  * hinawa_fw_node_get_config_rom:
  * @self: A [class@FwNode]
  * @image: (array length=length)(out)(transfer none): The content of configuration ROM.
- * @length: (out): The number of bytes consists of the configuration rom.
+ * @length: (out): The number of bytes consists of the configuration ROM.
  * @error: A [struct@GLib.Error].
  *
  * Get cached content of configuration ROM aligned to big-endian.
@@ -460,7 +459,8 @@ gboolean hinawa_fw_node_get_config_rom(HinawaFwNode *self, const guint8 **image,
  * @cycle_time: (inout): A [struct@CycleTime].
  * @error: A [struct@GLib.Error].
  *
- * Read current value of CYCLE_TIME register in 1394 OHCI hardware.
+ * Read current value of CYCLE_TIME register in 1394 OHCI hardware dedicated to communicate with
+ * the associated node in IEEE 1394 bus.
  *
  * Returns: TRUE if the overall operation finishes successfully, otherwise FALSE.
  *
diff --git a/src/fw_req.c b/src/fw_req.c
index b862575..a8ccc2a 100644
--- a/src/fw_req.c
+++ b/src/fw_req.c
@@ -9,11 +9,7 @@
  * HinawaFwReq:
  * A transaction executor to a node in IEEE 1394 bus.
  *
- * A HinawaFwReq supports some types of transactions in IEEE 1212. Mainly for read, write and lock
- * operations.
- *
- * This class is an application of Linux FireWire subsystem. All of operations utilize ioctl(2)
- * with subsystem specific request commands.
+ * [class@FwReq] supports all types of transactions defiend in IEEE 1212.
  */
 
 /**
@@ -65,10 +61,12 @@ static void hinawa_fw_req_class_init(HinawaFwReqClass *klass)
 	 * HinawaFwReq::responded:
 	 * @self: A [class@FwReq].
 	 * @rcode: One of [enum@FwRcode].
-	 * @request_tstamp: The isochronous cycle at which the request was sent.
-	 * @response_tstamp: The isochronous cycle at which the response arrived.
+	 * @request_tstamp: The isochronous cycle at which the request subaction was sent for the
+	 *		    transaction.
+	 * @response_tstamp: The isochronous cycle at which the response subaction arrived for the
+	 *		     transaction.
 	 * @frame: (array length=frame_size)(element-type guint8): The array with elements for
-	 *	   byte data of response subaction for transaction.
+	 *	   byte data of response subaction for the transaction.
 	 * @frame_size: The number of elements of the array.
 	 *
 	 * Emitted when the node transfers asynchronous packet as response subaction for the
@@ -127,11 +125,11 @@ HinawaFwReq *hinawa_fw_req_new(void)
  *	   to the array and immutable. The content of array is mutable for read and lock
  *	   transaction.
  * @frame_size: The size of array in byte unit. The value of this argument should point to the
- *		numerical number and mutable for read and lock transaction.
+ *		numeric number and mutable for read and lock transaction.
  * @error: A [struct@GLib.Error]. Error can be generated with two domains; Hinawa.FwNodeError and
  *	   Hinawa.FwReqError.
  *
- * Execute request subaction of transactions to the given node according to given code. When the
+ * Execute request subaction of transaction to the given node according to given code. When the
  * response subaction arrives and running event dispatcher reads the contents,
  * [signal@FwReq::responded] signal handler is called.
  *
@@ -252,9 +250,9 @@ static void handle_responded_signal(HinawaFwReq *self, HinawaFwRcode rcode, guin
  * @frame_size: The size of array in byte unit. The value of this argument should point to the
  *		numeric number and mutable for read and lock transaction.
  * @tstamp: (array fixed-size=2)(out caller-allocates): The array with two elements for time stamps.
- *	    The first element is for the isochronous cycle at which the request was sent. The second
- *	    element is for the isochronous cycle at which the response arrived.
- * @timeout_ms: The timeout to wait for response subaction of the transaction since request
+ *	    The first element is for the isochronous cycle at which the request subaction was sent.
+ *	    The second element is for the isochronous cycle at which the response subaction arrived.
+ * @timeout_ms: The timeout to wait for the response subaction of transaction since the request
  *		subaction is initiated, in milliseconds.
  * @error: A [struct@GLib.Error]. Error can be generated with two domains; Hinawa.FwNodeError and
  *	   Hinawa.FwReqError.
diff --git a/src/fw_req.h b/src/fw_req.h
index e2df665..eba16db 100644
--- a/src/fw_req.h
+++ b/src/fw_req.h
@@ -21,10 +21,12 @@ struct _HinawaFwReqClass {
 	 * HinawaFwReqClass::responded:
 	 * @self: A [class@FwReq].
 	 * @rcode: One of [enum@FwRcode].
-	 * @request_tstamp: The isochronous cycle at which the request was sent.
-	 * @response_tstamp: The isochronous cycle at which the response arrived.
-	 * @frame: (array length=frame_size)(element-type guint8): The array with elements for
-	 *	   byte data of response subaction for transaction.
+	 * @request_tstamp: The isochronous cycle at which the request subaction was sent for the
+	 *		    transaction.
+	 * @response_tstamp: The isochronous cycle at which the response subaction arrived for the
+	 *		     transaction.
+	 * @frame: (array length=frame_size)(element-type guint8): The array with elements for byte
+	 *	   data of the response subaction of transaction.
 	 * @frame_size: The number of elements of the array.
 	 *
 	 * Class closure for the [signal@FwReq::responded] signal.
diff --git a/src/fw_resp.c b/src/fw_resp.c
index 32d94a1..728663d 100644
--- a/src/fw_resp.c
+++ b/src/fw_resp.c
@@ -9,10 +9,7 @@
  * HinawaFwResp:
  * A transaction responder for request subaction initiated by node in IEEE 1394 bus.
  *
- * The [class@FwResp] responds to request subaction initiated by node in IEEE 1394 bus.
- *
- * This class is an application of Linux FireWire subsystem. Some operations utilize ioctl(2)
- * with subsystem specific request commands.
+ * [class@FwResp] responds to request subaction initiated by node in IEEE 1394 bus.
  */
 
 /**
@@ -225,12 +222,12 @@ HinawaFwResp *hinawa_fw_resp_new(void)
  * @error: A [struct@GLib.Error]. Error can be generated with two domain of Hinawa.FwNodeError and
  *	   Hinawa.FwRespError.
  *
- * Allocate an address range within Linux system for local nodes, each of which represents 1394
+ * Allocate an address range within Linux system for local nodes, each of which expresses 1394
  * OHCI hardware. Once successful, [signal@FwResp::requested] signal will be emitted whenever any
  * request subactions arrive at the 1394 OHCI hardware within the dedicated range.
  *
  * The range is reserved between the values specified by @region_start and @region_end with the size
- * indicated by @width, The starting offset may vary every time.
+ * indicated by @width. The starting offset may vary every time.
  *
  * Returns: TRUE if the overall operation finishes successfully, otherwise FALSE.
  *
@@ -292,7 +289,7 @@ gboolean hinawa_fw_resp_reserve_within_region(HinawaFwResp *self, HinawaFwNode *
  * @error: A [struct@GLib.Error]. Error can be generated with two domain of Hinawa.FwNodeError and
  *	   and Hinawa.FwRespError.
  *
- * Allocate an address range within Linux system for local nodes, each of which represents 1394
+ * Allocate an address range within Linux system for local nodes, each of which expresses 1394
  * OHCI hardware. Once successful, [signal@FwResp::requested] signal will be emitted whenever any
  * request subactions arrive at the 1394 OHCI hardware within the dedicated range.
  *
@@ -314,7 +311,7 @@ gboolean hinawa_fw_resp_reserve(HinawaFwResp *self, HinawaFwNode *node, guint64
  * hinawa_fw_resp_release:
  * @self: A [class@FwResp].
  *
- * Stop listening to the address range in Linu system for local nodes.
+ * Stop listening to the address range in Linux system for local nodes.
  *
  * Since: 1.4
  */
@@ -353,10 +350,10 @@ void hinawa_fw_resp_release(HinawaFwResp *self)
 /**
  * hinawa_fw_resp_set_resp_frame:
  * @self: A [class@FwResp]
- * @frame: (element-type guint8)(array length=length): a 8bit array for response frame.
+ * @frame: (element-type guint8)(array length=length): a 8 bit array for response frame.
  * @length: The length of bytes for the frame.
  *
- * Register byte frame for the response subaction.
+ * Register byte frame for the response subaction of transaction.
  *
  * Since: 2.0
  */