fw_iso_tx: link optimization to gi-docgen

The gi-docgen supports enhancement of inter-document link. This commit is
optimization to it.

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

2 files changed, 42 insertions, 50 deletions

diff --git a/src/fw_iso_tx.c b/src/fw_iso_tx.c
index 9182833..07aed43 100644
--- a/src/fw_iso_tx.c
+++ b/src/fw_iso_tx.c
@@ -5,15 +5,12 @@
 #include <errno.h>
 
 /**
- * SECTION:fw_iso_tx
- * @Title: HinokoFwIsoTx
- * @Short_description: An object to transmit isochronous packet for single
- *		       channel.
- * @include: fw_iso_tx.h
+ * HinokoFwIsoTx:
+ * An object to transmit isochronous packet for single channel.
  *
- * A #HinokoFwIsoTx transmits isochronous packets for single channel by IT
- * context in 1394 OHCI. The content of packet is split to two parts; context
- * header and context payload in a manner of Linux FireWire subsystem.
+ * A [class@FwIsoTx] transmits isochronous packets for single channel by IT context in 1394 OHCI.
+ * The content of packet is split to two parts; context header and context payload in a manner of
+ * Linux FireWire subsystem.
  */
 typedef struct {
 	guint offset;
@@ -43,23 +40,22 @@ static void hinoko_fw_iso_tx_class_init(HinokoFwIsoTxClass *klass)
 
 	/**
 	 * HinokoFwIsoTx::interrupted:
-	 * @self: A #HinokoFwIsoTx.
+	 * @self: A [class@FwIsoTx].
 	 * @sec: sec part of isochronous cycle when interrupt occurs.
 	 * @cycle: cycle part of of isochronous cycle when interrupt occurs.
-	 * @tstamp: (array length=tstamp_length) (element-type guint8): A series
-	 *	    of timestamps for packets already handled.
+	 * @tstamp: (array length=tstamp_length) (element-type guint8): A series of timestamps for
+	 *	    packets already handled.
 	 * @tstamp_length: the number of bytes for @tstamp.
 	 * @count: the number of handled packets.
 	 *
-	 * When Linux FireWire subsystem generates interrupt event, the #HinokoFwIsoTx::interrupted
-	 * signal is emitted. There are three cases for Linux FireWire subsystem to generate the
-	 * event:
+	 * Emitted when Linux FireWire subsystem generates interrupt event. There are three cases
+	 * for Linux FireWire subsystem to generate the event:
 	 *
 	 * - When OHCI 1394 controller generates hardware interrupt as a result of processing the
 	 *   isochronous packet for the buffer chunk marked to generate hardware interrupt.
 	 * - When the number of isochronous packets sent since the last interrupt event reaches
 	 *   one quarter of memory page size (usually 4,096 / 4 = 1,024 packets).
-	 * - When application calls #hinoko_fw_iso_ctx_flush_completions() explicitly.
+	 * - When application calls [method@FwIsoCtx.flush_completions] explicitly.
 	 */
 	fw_iso_tx_sigs[FW_ISO_TX_SIG_TYPE_IRQ] =
 		g_signal_new("interrupted",
@@ -81,9 +77,9 @@ static void hinoko_fw_iso_tx_init(HinokoFwIsoTx *self)
 /**
  * hinoko_fw_iso_tx_new:
  *
- * Instantiate #HinokoFwIsoTx object and return the instance.
+ * Instantiate [class@FwIsoTx] object and return the instance.
  *
- * Returns: an instance of #HinokoFwIsoTx.
+ * Returns: an instance of [class@FwIsoTx].
  */
 HinokoFwIsoTx *hinoko_fw_iso_tx_new(void)
 {
@@ -92,16 +88,16 @@ HinokoFwIsoTx *hinoko_fw_iso_tx_new(void)
 
 /**
  * hinoko_fw_iso_tx_allocate:
- * @self: A #HinokoFwIsoTx.
+ * @self: A [class@FwIsoTx].
  * @path: A path to any Linux FireWire character device.
- * @scode: A #HinokoFwScode to indicate speed of isochronous communication.
+ * @scode: A [enum@FwScode] to indicate speed of isochronous communication.
  * @channel: An isochronous channel to transfer.
  * @header_size: The number of bytes for header of IT context.
- * @error: A #GError.
+ * @error: A [struct@GLib.Error].
  *
- * Allocate an IT context to 1394 OHCI controller. A local node of the node
- * corresponding to the given path is used as the controller, thus any path is
- * accepted as long as process has enough permission for the path.
+ * Allocate an IT context to 1394 OHCI controller. A local node of the node corresponding to the
+ * given path is used as the controller, thus any path is accepted as long as process has enough
+ * permission for the path.
  */
 void hinoko_fw_iso_tx_allocate(HinokoFwIsoTx *self, const char *path,
 			       HinokoFwScode scode, guint channel,
@@ -117,7 +113,7 @@ void hinoko_fw_iso_tx_allocate(HinokoFwIsoTx *self, const char *path,
 
 /**
  * hinoko_fw_iso_tx_release:
- * @self: A #HinokoFwIsoTx.
+ * @self: A [class@FwIsoTx].
  *
  * Release allocated IT context from 1394 OHCI controller.
  */
@@ -132,13 +128,12 @@ void hinoko_fw_iso_tx_release(HinokoFwIsoTx *self)
 
 /**
  * hinoko_fw_iso_tx_map_buffer:
- * @self: A #HinokoFwIsoTx.
+ * @self: A [class@FwIsoTx].
  * @maximum_bytes_per_payload: The number of bytes for payload of IT context.
  * @payloads_per_buffer: The number of payloads of IT context in buffer.
- * @error: A #GError.
+ * @error: A [struct@GLib.Error].
  *
- * Map intermediate buffer to share payload of IT context with 1394 OHCI
- * controller.
+ * Map intermediate buffer to share payload of IT context with 1394 OHCI controller.
  */
 void hinoko_fw_iso_tx_map_buffer(HinokoFwIsoTx *self,
 				 guint maximum_bytes_per_payload,
@@ -160,10 +155,9 @@ void hinoko_fw_iso_tx_map_buffer(HinokoFwIsoTx *self,
 
 /**
  * hinoko_fw_iso_tx_unmap_buffer:
- * @self: A #HinokoFwIsoTx.
+ * @self: A [class@FwIsoTx].
  *
- * Unmap intermediate buffer shard with 1394 OHCI controller for payload
- * of IT context.
+ * Unmap intermediate buffer shard with 1394 OHCI controller for payload of IT context.
  */
 void hinoko_fw_iso_tx_unmap_buffer(HinokoFwIsoTx *self)
 {
@@ -176,13 +170,12 @@ void hinoko_fw_iso_tx_unmap_buffer(HinokoFwIsoTx *self)
 
 /**
  * hinoko_fw_iso_tx_start:
- * @self: A #HinokoFwIsoTx.
- * @cycle_match: (array fixed-size=2) (element-type guint16) (in) (nullable):
- * 		 The isochronous cycle to start packet processing. The first
- * 		 element should be the second part of isochronous cycle, up to
- * 		 3. The second element should be the cycle part of isochronous
- * 		 cycle, up to 7999.
- * @error: A #GError.
+ * @self: A [class@FwIsoTx].
+ * @cycle_match: (array fixed-size=2) (element-type guint16) (in) (nullable): The isochronous cycle
+ *		 to start packet processing. The first element should be the second part of
+ *		 isochronous cycle, up to 3. The second element should be the cycle part of
+ *		 isochronous cycle, up to 7999.
+ * @error: A [struct@GLib.Error].
  *
  * Start IT context.
  *
@@ -199,7 +192,7 @@ void hinoko_fw_iso_tx_start(HinokoFwIsoTx *self, const guint16 *cycle_match, GEr
 
 /**
  * hinoko_fw_iso_tx_stop:
- * @self: A #HinokoFwIsoTx.
+ * @self: A [class@FwIsoTx].
  *
  * Stop IT context.
  */
@@ -217,21 +210,20 @@ void hinoko_fw_iso_tx_stop(HinokoFwIsoTx *self)
 
 /**
  * hinoko_fw_iso_tx_register_packet:
- * @self: A #HinokoFwIsoTx.
+ * @self: A [class@FwIsoTx].
  * @tags: The value of tag field for isochronous packet to register.
  * @sy: The value of sy field for isochronous packet to register.
- * @header: (array length=header_length)(nullable): The header of IT context
- * 	    for isochronous packet.
+ * @header: (array length=header_length)(nullable): The header of IT context for isochronous packet.
  * @header_length: The number of bytes for the @header.
- * @payload: (array length=payload_length)(nullable): The payload of IT context
- * 	     for isochronous packet.
+ * @payload: (array length=payload_length)(nullable): The payload of IT context for isochronous
+ *	     packet.
  * @payload_length: The number of bytes for the @payload.
  * @schedule_interrupt: Whether to schedule hardware interrupt at isochronous cycle for the packet.
- * @error: A #GError.
+ * @error: A [struct@GLib.Error].
  *
  * Register packet data with header and payload for IT context. The caller can schedule hardware
  * interrupt to generate interrupt event. In detail, please refer to documentation about
- * #HinokoFwIsoTx::interrupted.
+ * [signal@FwIsoTx::interrupted].
  *
  * Since: 0.6.
  */
diff --git a/src/fw_iso_tx.h b/src/fw_iso_tx.h
index f64fe0d..92f2bba 100644
--- a/src/fw_iso_tx.h
+++ b/src/fw_iso_tx.h
@@ -15,15 +15,15 @@ struct _HinokoFwIsoTxClass {
 
 	/**
 	 * HinokoFwIsoTxClass::interrupted:
-	 * @self: A #HinokoFwIsoTx.
+	 * @self: A [class@FwIsoTx].
 	 * @sec: sec part of isochronous cycle when interrupt occurs.
 	 * @cycle: cycle part of of isochronous cycle when interrupt occurs.
-	 * @tstamp: (array length=tstamp_length) (element-type guint8): A series
-	 *	    of timestamps for packets already handled.
+	 * @tstamp: (array length=tstamp_length) (element-type guint8): A series of timestamps for
+	 *	    packets already handled.
 	 * @tstamp_length: the number of bytes for @tstamp.
 	 * @count: the number of handled packets.
 	 *
-	 * In detail, please refer to documentation about #HinokoFwIsoTx::interrupted.
+	 * Class closure for the [signal@FwIsoTx::interrupted] signal.
 	 */
 	void (*interrupted)(HinokoFwIsoTx *self, guint sec, guint cycle,
 			    const guint8 *tstamp, guint tstamp_length,