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

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

[Kent Gibson]

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(-)

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.
-- 
2.40.1

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

[Bartosz Golaszewski]

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

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

[Kent Gibson]

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.