diff mbox series

[libgpiod] core: doc: add doc for opaque structs to link to the relevant page

Message ID 20230609073957.72418-1-warthog618@gmail.com
State New
Headers show
Series [libgpiod] core: doc: add doc for opaque structs to link to the relevant page | expand

Commit Message

Kent Gibson June 9, 2023, 7:39 a.m. UTC
The C doxygen documentation is difficult to navigate as the opaque types
do not get linked to anything.

Add doc for each opaque struct that references the relevant page.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---

There might be a better way to do this, but this the best I've run
across so far.  At least the generated doc is navigable without having to
return to the modules page and perform mental gymnastics.

Along the way, also renamed the request_request group to line_request as
that makes more sense.

Haven't pushed this one to rtd yet, as this is a more significant
change - not just fixing a typo.

Cheers,
Kent.

 include/gpiod.h | 66 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

Comments

Bartosz Golaszewski June 9, 2023, 8:17 p.m. UTC | #1
On Fri, Jun 9, 2023 at 9:40 AM Kent Gibson <warthog618@gmail.com> wrote:
>
> The C doxygen documentation is difficult to navigate as the opaque types
> do not get linked to anything.
>
> Add doc for each opaque struct that references the relevant page.
>
> Signed-off-by: Kent Gibson <warthog618@gmail.com>
> ---
>
> There might be a better way to do this, but this the best I've run
> across so far.  At least the generated doc is navigable without having to
> return to the modules page and perform mental gymnastics.
>
> Along the way, also renamed the request_request group to line_request as
> that makes more sense.
>
> Haven't pushed this one to rtd yet, as this is a more significant
> change - not just fixing a typo.
>
> Cheers,
> Kent.
>

Thanks for doing this. I tweaked the patch a little bit and applied to master.

Bart
Kent Gibson June 10, 2023, 12:27 a.m. UTC | #2
On Fri, Jun 09, 2023 at 10:17:13PM +0200, Bartosz Golaszewski wrote:
> On Fri, Jun 9, 2023 at 9:40 AM Kent Gibson <warthog618@gmail.com> wrote:
> >
> 
> Thanks for doing this. I tweaked the patch a little bit and applied to master.
> 

rtd updated with those two doc patches applied to v2.0.1.

Cheers,
Kent.
diff mbox series

Patch

diff --git a/include/gpiod.h b/include/gpiod.h
index d1833de..d459151 100644
--- a/include/gpiod.h
+++ b/include/gpiod.h
@@ -44,15 +44,79 @@  extern "C" {
  * handling it, ignoring it or returning an error.
  */
 
+/**
+ * @struct gpiod_chip
+ * @{
+ *  Refer to @ref chips for functions that operate on gpiod_chip.
+ * @}
+*/
 struct gpiod_chip;
+/**
+ * @struct gpiod_chip_info
+ * @{
+ *  Refer to @ref chip_info for functions that operate on gpiod_chip_info.
+ * @}
+*/
 struct gpiod_chip_info;
+/**
+ * @struct gpiod_line_info
+ * @{
+ *  Refer to @ref line_info for functions that operate on gpiod_line_info.
+ * @}
+*/
 struct gpiod_line_info;
+/**
+ * @struct gpiod_line_settings
+ * @{
+ *  Refer to @ref line_settings for functions that operate on
+ *  gpiod_line_settings.
+ * @}
+*/
 struct gpiod_line_settings;
+/**
+ * @struct gpiod_line_config
+ * @{
+ *  Refer to  @ref line_config for functions that operate on gpiod_line_config.
+ * @}
+*/
 struct gpiod_line_config;
+/**
+ * @struct gpiod_request_config
+ * @{
+ *  Refer to  @ref request_config for functions that operate on
+ *  gpiod_request_config.
+ * @}
+*/
 struct gpiod_request_config;
+/**
+ * @struct gpiod_line_request
+ * @{
+ *  Refer to  @ref line_request for functions that operate on
+ *  gpiod_line_request.
+ * @}
+*/
 struct gpiod_line_request;
+/**
+ * @struct gpiod_info_event
+ * @{
+ *  Refer to  @ref line_watch for functions that operate on gpiod_info_event.
+ * @}
+*/
 struct gpiod_info_event;
+/**
+ * @struct gpiod_edge_event
+ * @{
+ *  Refer to  @ref edge_event for functions that operate on gpiod_edge_event.
+ * @}
+*/
 struct gpiod_edge_event;
+/**
+ * @struct gpiod_edge_event_buffer
+ * @{
+ *  Refer to  @ref edge_event for functions that operate on
+ *  gpiod_edge_event_buffer.
+ * @}
+*/
 struct gpiod_edge_event_buffer;
 
 /**
@@ -902,7 +966,7 @@  gpiod_request_config_get_event_buffer_size(struct gpiod_request_config *config);
 /**
  * @}
  *
- * @defgroup request_request Line request operations
+ * @defgroup line_request Line request operations
  * @{
  *
  * Functions allowing interactions with requested lines.