Re: [libgpiod v2][PATCH 6/6] doc: API documentation tweaks

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Fri, Mar 11, 2022 at 8:41 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>
> A collection of tweaks to the API documentation in gpiod.h
>
> Signed-off-by: Kent Gibson <warthog618@xxxxxxxxx>
> ---

Thanks for doing this. I applied everything except for the following
rejects as I think we should keep num_values for the argument name.

Bart

--- include/gpiod.h
+++ include/gpiod.h
@@ -951,12 +969,13 @@
gpiod_line_config_set_output_value_override(struct gpiod_line_config
*config,
      unsigned int offset, int value);

 /**
- * @brief Override the output values for multiple offsets.
+ * @brief Override the output values for multiple lines.
  * @param config Line config object.
  * @param num_lines Number of lines for which to override values.
- * @param offsets Array of line offsets to override values for.
- * @param values Array of output values associated with the offsets passed in
- *               the previous argument.
+ * @param offsets Array of offsets indentifying the lines for which to override
+ *   values,  containing \p num_lines entries.
+ * @param values Array of output values corresponding to the lines
identified in
+ * \p offsets, also containing \p num_lines entries.
  */
 void gpiod_line_config_set_output_values(struct gpiod_line_config *config,
  size_t num_lines,
@@ -1090,57 +1107,60 @@ void gpiod_request_config_set_consumer(struct
gpiod_request_config *config,
         const char *consumer);

 /**
- * @brief Get the consumer string.
+ * @brief Get the consumer name configured in the request config.
  * @param config Request config object.
- * @return Current consumer string stored in this request config.
+ * @return Consumer name stored in the request config.
  */
 const char *
 gpiod_request_config_get_consumer(struct gpiod_request_config *config);

 /**
- * @brief Set line offsets for this request.
+ * @brief Set the offsets of the lines to be requested.
  * @param config Request config object.
- * @param num_offsets Number of offsets.
- * @param offsets Array of line offsets.
- * @note If too many offsets were specified, the offsets above the limit
+ * @param num_lines Number of lines, which specifies the size of the offsets
+ *   array.
+ * @param offsets Array of offsets of the lines.
+ * @note If too many lines were specified, the offsets above the limit
  *       accepted by the kernel (64 lines) are silently dropped.
  */
 void gpiod_request_config_set_offsets(struct gpiod_request_config *config,
-       size_t num_offsets,
+       size_t num_lines,
        const unsigned int *offsets);

 /**
- * @brief Get the number of lines configured in this request config.
+ * @brief Get the number of lines configured in the request config.
  * @param config Request config object.
- * @return Number of lines to be requested by this config.
+ * @return Number of lines to be requested by the config.
  */
 size_t
 gpiod_request_config_get_num_lines(struct gpiod_request_config *config);

 /**
- * @brief Get the hardware offsets of lines in this request config.
+ * @brief Get the offsets of lines configured in the request config.
  * @param config Request config object.
- * @param offsets Array to store offsets. Must hold at least the number of
- *                lines returned by ::gpiod_request_config_get_num_offsets.
+ * @param offsets Array to store offsets. Must be sized to hold the number of
+ *   lines returned by ::gpiod_request_config_get_num_lines.
  */
 void gpiod_request_config_get_offsets(struct gpiod_request_config *config,
-       unsigned int *offsets);
+     unsigned int *offsets);

 /**
- * @brief Set the size of the kernel event buffer.
+ * @brief Set the size of the kernel event buffer for the request.
  * @param config Request config object.
  * @param event_buffer_size New event buffer size.
  * @note The kernel may adjust the value if it's too high. If set to 0, the
  *       default value will be used.
+ * @note The kernel buffer is distinct from and independent of the user space
+ * buffer (::gpiod_edge_event_buffer_new).
  */
 void
 gpiod_request_config_set_event_buffer_size(struct gpiod_request_config *config,
     size_t event_buffer_size);

 /**
- * @brief Get the edge event buffer size from this request config.
+ * @brief Get the edge event buffer size for the request config.
  * @param config Request config object.
- * @return Current edge event buffer size setting.
+ * @return Edge event buffer size setting from the request config.
  */
 size_t
 gpiod_request_config_get_event_buffer_size(struct
gpiod_request_config *config);