From: Bert Vermeulen <redacted>
Date: Tue, 23 Sep 2014 10:05:31 +0000 (+0200)
Subject: Clean up internal input API docs.
X-Git-Tag: libsigrok-0.4.0~916
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=753793eff5f713e07a42f2c7a177502aeb764654;p=libsigrok.git

Clean up internal input API docs.
---

diff --git a/src/libsigrok-internal.h b/src/libsigrok-internal.h
index faac4647..655fdeb6 100644
--- a/src/libsigrok-internal.h
+++ b/src/libsigrok-internal.h
@@ -265,7 +265,7 @@ struct sr_input_module {
 	 * @param[in] metadata Metadata the module can use to identify the stream.
 	 *
 	 * @retval SR_OK This module knows the format.
-	 * @retval SR_OK_CONTINUE There wasn't enough data for this module to
+	 * @retval SR_ERR_NA There wasn't enough data for this module to
 	 *   positively identify the format.
 	 * @retval SR_ERR_DATA This module knows the format, but cannot handle it.
 	 *   This means the stream is either corrupt, or indicates a feature
@@ -277,38 +277,34 @@ struct sr_input_module {
 	/**
 	 * Initialize the input module.
 	 *
-	 * @param in A pointer to a valid 'struct sr_input' that the caller
-	 *           has to allocate and provide to this function. It is also
-	 *           the responsibility of the caller to free it later.
-	 * @param[in] filename The name (and path) of the file to use.
-	 *
 	 * @retval SR_OK Success
 	 * @retval other Negative error code.
 	 */
 	int (*init) (struct sr_input *in, GHashTable *options);
 
 	/**
-	 * Load a file, parsing the input according to the file's format.
-	 *
-	 * This function will send datafeed packets to the session bus, so
-	 * the calling frontend must have registered its session callbacks
-	 * beforehand.
+	 * Send data to the specified input instance.
 	 *
-	 * The packet types sent across the session bus by this function must
-	 * include at least SR_DF_HEADER, SR_DF_END, and an appropriate data
-	 * type such as SR_DF_LOGIC. It may also send a SR_DF_TRIGGER packet
-	 * if appropriate.
+	 * When an input module instance is created with sr_input_new(), this
+	 * function is used to feed data to the instance.
 	 *
-	 * @param in A pointer to a valid 'struct sr_input' that the caller
-	 *           has to allocate and provide to this function. It is also
-	 *           the responsibility of the caller to free it later.
-	 * @param f The name (and path) of the file to use.
+	 * As enough data gets fed into this function to completely populate
+	 * the device instance associated with this input instance, this is
+	 * guaranteed to return the moment it's ready. This gives the caller
+	 * the chance to examine the device instance, attach session callbacks
+	 * and so on.
 	 *
 	 * @retval SR_OK Success
 	 * @retval other Negative error code.
 	 */
 	int (*receive) (struct sr_input *in, GString *buf);
 
+	/**
+	 * Signal the input module no more data will come.
+	 *
+	 * This will cause the module to process any data it may have buffered.
+	 * The SR_DF_END packet will also typically be sent at this time.
+	 */
 	int (*end) (struct sr_input *in);
 
 	/**
@@ -316,6 +312,8 @@ struct sr_input_module {
 	 * the input module, and can be used to free any internal
 	 * resources the module may keep.
 	 *
+	 * This function is optional.
+	 *
 	 * @retval SR_OK Success
 	 * @retval other Negative error code.
 	 */