scpi: document callers' responsibility to free getters' allocated memory

Some of the SCPI getter routines allocate memory for response data which
callers need to free after use. Document this responsibility in more
places, and rephrase existing locations for consistency. See a word-diff
for the essence of the commit.

It's assumed that the separate paragraph in the function description is
better perceived than something that's hidden in the parameter or return
value discussion. Also reference the corresponding free routine by name
for callers' convenience (data types will differ among routines). Some
free routines can be called unconditionally, others require NULL checks
at the caller's.

Reported-By: Ralf <redacted>

diff --git a/src/scpi/scpi.c b/src/scpi/scpi.c
index c01791ef5ecebc8ac43300db1248a36081951f92..0f767f2a2de1c6862b61620d6e2dc0b9178c2f7d 100644 (file)
--- a/src/scpi/scpi.c
+++ b/src/scpi/scpi.c
@@ -410,9 +410,11 @@ SR_PRIV int sr_scpi_open(struct sr_scpi_dev_inst *scpi)
 /**
  * Get the connection ID of the SCPI device.
  *
- * @param scpi Previously initialized SCPI device structure.
- * @param connection_id Pointer where to store the connection ID. The caller
- *        is responsible for g_free()ing the string when it is no longer needed.
+ * Callers must free the allocated memory regardless of the routine's
+ * return code. See @ref g_free().
+ *
+ * @param[in] scpi Previously initialized SCPI device structure.
+ * @param[out] connection_id Pointer where to store the connection ID.
  *
  * @return SR_OK on success, SR_ERR on failure.
  */
@@ -610,9 +612,12 @@ SR_PRIV void sr_scpi_free(struct sr_scpi_dev_inst *scpi)
 /**
  * Send a SCPI command, receive the reply and store the reply in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the SCPI response.
+ * Callers must free the allocated memory regardless of the routine's
+ * return code. See @ref g_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the SCPI response.
  *
  * @return SR_OK on success, SR_ERR* on failure.
  */
@@ -841,14 +846,15 @@ SR_PRIV int sr_scpi_get_opc(struct sr_scpi_dev_inst *scpi)
  * Send a SCPI command, read the reply, parse it as comma separated list of
  * floats and store the as an result in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the parsed result.
+ * Callers must free the allocated memory (unless it's NULL) regardless of
+ * the routine's return code. See @ref g_array_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the parsed result.
  *
  * @return SR_OK upon successfully parsing all values, SR_ERR* upon a parsing
- *         error or upon no response. The allocated response must be freed by
- *         the caller in the case of an SR_OK as well as in the case of
- *         parsing error.
+ *         error or upon no response.
  */
 SR_PRIV int sr_scpi_get_floatv(struct sr_scpi_dev_inst *scpi,
                               const char *command, GArray **scpi_response)
@@ -898,14 +904,15 @@ SR_PRIV int sr_scpi_get_floatv(struct sr_scpi_dev_inst *scpi,
  * Send a SCPI command, read the reply, parse it as comma separated list of
  * unsigned 8 bit integers and store the as an result in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the parsed result.
+ * Callers must free the allocated memory (unless it's NULL) regardless of
+ * the routine's return code. See @ref g_array_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the parsed result.
  *
  * @return SR_OK upon successfully parsing all values, SR_ERR* upon a parsing
- *         error or upon no response. The allocated response must be freed by
- *         the caller in the case of an SR_OK as well as in the case of
- *         parsing error.
+ *         error or upon no response.
  */
 SR_PRIV int sr_scpi_get_uint8v(struct sr_scpi_dev_inst *scpi,
                               const char *command, GArray **scpi_response)
@@ -954,14 +961,15 @@ SR_PRIV int sr_scpi_get_uint8v(struct sr_scpi_dev_inst *scpi,
  * Send a SCPI command, read the reply, parse it as binary data with a
  * "definite length block" header and store the as an result in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the parsed result.
+ * Callers must free the allocated memory (unless it's NULL) regardless of
+ * the routine's return code. See @ref g_byte_array_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the parsed result.
  *
  * @return SR_OK upon successfully parsing all values, SR_ERR* upon a parsing
- *         error or upon no response. The allocated response must be freed by
- *         the caller in the case of an SR_OK as well as in the case of
- *         parsing error.
+ *         error or upon no response.
  */
 SR_PRIV int sr_scpi_get_block(struct sr_scpi_dev_inst *scpi,
                               const char *command, GByteArray **scpi_response)
@@ -1094,10 +1102,11 @@ SR_PRIV int sr_scpi_get_block(struct sr_scpi_dev_inst *scpi,
  * Send the *IDN? SCPI command, receive the reply, parse it and store the
  * reply as a sr_scpi_hw_info structure in the supplied scpi_response pointer.
  *
- * The hw_info structure must be freed by the caller via sr_scpi_hw_info_free().
+ * Callers must free the allocated memory regardless of the routine's
+ * return code. See @ref sr_scpi_hw_info_free().
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param scpi_response Pointer where to store the hw_info structure.
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[out] scpi_response Pointer where to store the hw_info structure.
  *
  * @return SR_OK upon success, SR_ERR* on failure.
  */