[libgpiod] [PATCH 0/5] Documentation improvements

[libgpiod] [PATCH 0/5] Documentation improvements

[Alexander Stein]

Hey,
this changeset improves the document generation by reducing warnings
as well as supporting building doc out of tree now.

Alexander Stein (5):
  doc: Fix doxygen warnings
  doc: Use autotoolized Doxyfile
  doc: Fix doxygen warning
  doc: Remove obsolete PERL_PATH
  doc: Add @file to headers

 .gitignore              |  1 +
 Doxyfile => Doxyfile.in |  8 ++++----
 Makefile.am             |  4 +---
 bindings/cxx/gpiod.hpp  |  6 +++++-
 configure.ac            |  1 +
 include/gpiod.h         | 30 +++++++++++++++++-------------
 6 files changed, 29 insertions(+), 21 deletions(-)
 rename Doxyfile => Doxyfile.in (93%)

-- 
2.28.0

[libgpiod] [PATCH 1/5] doc: Fix doxygen warnings

[Alexander Stein]

Apparently __<name>__ is not supported for @defgroup commands. This results
in the following warning (printed multiple time):
gpiod.h:79: warning: group strong: ignoring title ">high_level</strong> High-level
API" that does not match old title ">common</strong> Common helper macros"
Also the module list is broken.

Fix this my removing the underscores.

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
---
 bindings/cxx/gpiod.hpp |  2 +-
 include/gpiod.h        | 26 +++++++++++++-------------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/bindings/cxx/gpiod.hpp b/bindings/cxx/gpiod.hpp
index 5155bdd..59719aa 100644
--- a/bindings/cxx/gpiod.hpp
+++ b/bindings/cxx/gpiod.hpp
@@ -24,7 +24,7 @@ class chip_iter;
 struct line_event;
 
 /**
- * @defgroup __gpiod_cxx__ C++ bindings
+ * @defgroup gpiod_cxx C++ bindings
  * @{
  */
 
diff --git a/include/gpiod.h b/include/gpiod.h
index c83ebf7..58de66f 100644
--- a/include/gpiod.h
+++ b/include/gpiod.h
@@ -46,7 +46,7 @@ struct gpiod_line_iter;
 struct gpiod_line_bulk;
 
 /**
- * @defgroup __common__ Common helper macros
+ * @defgroup common Common helper macros
  * @{
  *
  * Commonly used utility macros.
@@ -77,7 +77,7 @@ struct gpiod_line_bulk;
 /**
  * @}
  *
- * @defgroup __high_level__ High-level API
+ * @defgroup high_level High-level API
  * @{
  *
  * Simple high-level routines for straightforward GPIO manipulation without
@@ -548,7 +548,7 @@ int gpiod_ctxless_find_line(const char *name, char *chipname,
 /**
  * @}
  *
- * @defgroup __chips__ GPIO chip operations
+ * @defgroup chips GPIO chip operations
  * @{
  *
  * Functions and data structures dealing with GPIO chips.
@@ -691,12 +691,12 @@ int gpiod_chip_find_lines(struct gpiod_chip *chip, const char **names,
 /**
  * @}
  *
- * @defgroup __lines__ GPIO line operations
+ * @defgroup lines GPIO line operations
  * @{
  *
  * Functions and data structures dealing with GPIO lines.
  *
- * @defgroup __line_bulk__ Operating on multiple lines
+ * @defgroup line_bulk Operating on multiple lines
  * @{
  *
  * Convenience data structures and helper functions for storing and operating
@@ -807,7 +807,7 @@ gpiod_line_bulk_num_lines(struct gpiod_line_bulk *bulk)
 /**
  * @}
  *
- * @defgroup __line_info__ Line info
+ * @defgroup line_info Line info
  * @{
  *
  * Definitions and functions for retrieving kernel information about both
@@ -955,7 +955,7 @@ gpiod_line_needs_update(struct gpiod_line *line) GPIOD_API GPIOD_DEPRECATED;
 /**
  * @}
  *
- * @defgroup __line_request__ Line requests
+ * @defgroup line_request Line requests
  * @{
  *
  * Interface for requesting GPIO lines from userspace for both values and
@@ -1283,7 +1283,7 @@ bool gpiod_line_is_free(struct gpiod_line *line) GPIOD_API;
 /**
  * @}
  *
- * @defgroup __line_value__ Reading & setting line values
+ * @defgroup line_value Reading & setting line values
  * @{
  *
  * Functions allowing to read and set GPIO line values for single lines and
@@ -1338,7 +1338,7 @@ int gpiod_line_set_value_bulk(struct gpiod_line_bulk *bulk,
 /**
  * @}
  *
- * @defgroup __line_config__ Setting line configuration
+ * @defgroup line_config Setting line configuration
  * @{
  *
  * Functions allowing modification of config options of GPIO lines requested
@@ -1454,7 +1454,7 @@ int gpiod_line_set_direction_output_bulk(struct gpiod_line_bulk *bulk,
 /**
  * @}
  *
- * @defgroup __line_event__ Line events handling
+ * @defgroup line_event Line events handling
  * @{
  *
  * Structures and functions allowing to poll lines for events and read them,
@@ -1568,7 +1568,7 @@ int gpiod_line_event_read_fd_multiple(int fd, struct gpiod_line_event *events,
 /**
  * @}
  *
- * @defgroup __line_misc__ Misc line functions
+ * @defgroup line_misc Misc line functions
  * @{
  *
  * Functions that didn't fit anywhere else.
@@ -1624,7 +1624,7 @@ struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line) GPIOD_API;
  *
  * @}
  *
- * @defgroup __iterators__ Iterators for GPIO chips and lines
+ * @defgroup iterators Iterators for GPIO chips and lines
  * @{
  *
  * These functions and data structures allow easy iterating over GPIO
@@ -1748,7 +1748,7 @@ gpiod_line_iter_next(struct gpiod_line_iter *iter) GPIOD_API;
 /**
  * @}
  *
- * @defgroup __misc__ Stuff that didn't fit anywhere else
+ * @defgroup misc Stuff that didn't fit anywhere else
  * @{
  *
  * Various libgpiod-related functions.
-- 
2.28.0

[libgpiod] [PATCH 2/5] doc: Use autotoolized Doxyfile

[Alexander Stein]

This has several advantages:
* More simplified Makefile.am
* Actually used doxygen config is available as a file
* Building doc out-of-tree is possible

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
---
 .gitignore              | 1 +
 Doxyfile => Doxyfile.in | 3 ++-
 Makefile.am             | 4 +---
 configure.ac            | 1 +
 4 files changed, 5 insertions(+), 4 deletions(-)
 rename Doxyfile => Doxyfile.in (95%)

diff --git a/.gitignore b/.gitignore
index 488d9d6..a77efde 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ doc
 # autotools stuff
 .deps/
 .libs/
+Doxyfile
 Makefile
 Makefile.in
 aclocal.m4
diff --git a/Doxyfile b/Doxyfile.in
similarity index 95%
rename from Doxyfile
rename to Doxyfile.in
index b194095..8c6d591 100644
--- a/Doxyfile
+++ b/Doxyfile.in
@@ -10,6 +10,7 @@
 
 # General configuration
 PROJECT_NAME           = libgpiod
+PROJECT_NUMBER         = @VERSION_STR@
 OUTPUT_DIRECTORY       = doc
 OUTPUT_LANGUAGE        = English
 EXTRACT_ALL            = NO
@@ -48,7 +49,7 @@ WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = YES
 WARN_FORMAT            =
 WARN_LOGFILE           =
-INPUT                  = include/gpiod.h
+INPUT                  = @top_srcdir@/include/gpiod.h @top_srcdir@/bindings/cxx/gpiod.hpp
 SOURCE_BROWSER         = YES
 INLINE_SOURCES         = NO
 REFERENCED_BY_RELATION = YES
diff --git a/Makefile.am b/Makefile.am
index d3f57b2..72e6a25 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -29,9 +29,7 @@ SUBDIRS += bindings
 if HAS_DOXYGEN
 
 doc:
-	@(cat Doxyfile; \
-		echo PROJECT_NUMBER = $(VERSION_STR); \
-		echo INPUT += bindings/cxx/gpiod.hpp) | doxygen -
+	@doxygen Doxyfile
 .PHONY: doc
 
 clean-local:
diff --git a/configure.ac b/configure.ac
index 008499d..c2d9f99 100644
--- a/configure.ac
+++ b/configure.ac
@@ -207,6 +207,7 @@ if test "x$has_doxygen" = xfalse
 then
 	AC_MSG_NOTICE([doxygen not found - documentation cannot be generated])
 fi
+AM_COND_IF([HAS_DOXYGEN], [AC_CONFIG_FILES([Doxyfile])])
 
 if test "x$cross_compiling" = xno
 then
-- 
2.28.0

[libgpiod] [PATCH 3/5] doc: Fix doxygen warning

[Alexander Stein]

This fixes the warning
warning: argument 'a4wide' for option PAPER_TYPE is not a valid enum value
Using the default: a4!

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
---
 Doxyfile.in | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doxyfile.in b/Doxyfile.in
index 8c6d591..813ab31 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -79,7 +79,7 @@ TREEVIEW_WIDTH         = 250
 GENERATE_LATEX         = NO
 LATEX_OUTPUT           =
 COMPACT_LATEX          = NO
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 EXTRA_PACKAGES         =
 LATEX_HEADER           =
 PDF_HYPERLINKS         = NO
-- 
2.28.0

[libgpiod] [PATCH 4/5] doc: Remove obsolete PERL_PATH

[Alexander Stein]

This fixes the warning:
warning: Tag 'PERL_PATH' at line 110 of file 'Doxyfile' has become obsolete.

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
---
 Doxyfile.in | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Doxyfile.in b/Doxyfile.in
index 813ab31..4abad2d 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -107,4 +107,3 @@ GENERATE_XML           = YES
 TAGFILES               =
 GENERATE_TAGFILE       =
 ALLEXTERNALS           = NO
-PERL_PATH              =
-- 
2.28.0

[libgpiod] [PATCH 5/5] doc: Add @file to headers

[Alexander Stein]

This is necessary to have a file reference linked in the file list.
Also strip the top_srcdir from paths

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
---
 Doxyfile.in            | 2 +-
 bindings/cxx/gpiod.hpp | 4 ++++
 include/gpiod.h        | 4 ++++
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/Doxyfile.in b/Doxyfile.in
index 4abad2d..be2d250 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -22,7 +22,7 @@ BRIEF_MEMBER_DESC      = YES
 REPEAT_BRIEF           = YES
 ALWAYS_DETAILED_SEC    = NO
 FULL_PATH_NAMES        = NO
-STRIP_FROM_PATH        =
+STRIP_FROM_PATH        = @top_srcdir@
 INTERNAL_DOCS          = NO
 STRIP_CODE_COMMENTS    = YES
 CASE_SENSE_NAMES       = YES
diff --git a/bindings/cxx/gpiod.hpp b/bindings/cxx/gpiod.hpp
index 59719aa..8dfc172 100644
--- a/bindings/cxx/gpiod.hpp
+++ b/bindings/cxx/gpiod.hpp
@@ -23,6 +23,10 @@ class line_iter;
 class chip_iter;
 struct line_event;
 
+/**
+ * @file gpiod.hpp
+ */
+
 /**
  * @defgroup gpiod_cxx C++ bindings
  * @{
diff --git a/include/gpiod.h b/include/gpiod.h
index 58de66f..d1f9830 100644
--- a/include/gpiod.h
+++ b/include/gpiod.h
@@ -16,6 +16,10 @@
 extern "C" {
 #endif
 
+/**
+ * @file gpiod.h
+ */
+
 /**
  * @mainpage libgpiod public API
  *
-- 
2.28.0

Re: [libgpiod] [PATCH 0/5] Documentation improvements

[Bartosz Golaszewski]

On Sat, Aug 8, 2020 at 12:06 PM Alexander Stein
<alexander.stein@mailbox.org> wrote:
>
> Hey,
> this changeset improves the document generation by reducing warnings
> as well as supporting building doc out of tree now.
>
> Alexander Stein (5):
>   doc: Fix doxygen warnings
>   doc: Use autotoolized Doxyfile
>   doc: Fix doxygen warning
>   doc: Remove obsolete PERL_PATH
>   doc: Add @file to headers
>
>  .gitignore              |  1 +
>  Doxyfile => Doxyfile.in |  8 ++++----
>  Makefile.am             |  4 +---
>  bindings/cxx/gpiod.hpp  |  6 +++++-
>  configure.ac            |  1 +
>  include/gpiod.h         | 30 +++++++++++++++++-------------
>  6 files changed, 29 insertions(+), 21 deletions(-)
>  rename Doxyfile => Doxyfile.in (93%)
>
> --
> 2.28.0
>

Thanks for sending those! I guess I don't see any of the warnings you
mention because doxygen on my laptop is too old (1.8.13)?

Bartosz

Re: [libgpiod] [PATCH 0/5] Documentation improvements

[Kent Gibson]

On Mon, Aug 10, 2020 at 06:49:21PM +0200, Bartosz Golaszewski wrote:
> On Sat, Aug 8, 2020 at 12:06 PM Alexander Stein
> <alexander.stein@mailbox.org> wrote:
> >
> > Hey,
> > this changeset improves the document generation by reducing warnings
> > as well as supporting building doc out of tree now.
> >
> > Alexander Stein (5):
> >   doc: Fix doxygen warnings
> >   doc: Use autotoolized Doxyfile
> >   doc: Fix doxygen warning
> >   doc: Remove obsolete PERL_PATH
> >   doc: Add @file to headers
> >
> >  .gitignore              |  1 +
> >  Doxyfile => Doxyfile.in |  8 ++++----
> >  Makefile.am             |  4 +---
> >  bindings/cxx/gpiod.hpp  |  6 +++++-
> >  configure.ac            |  1 +
> >  include/gpiod.h         | 30 +++++++++++++++++-------------
> >  6 files changed, 29 insertions(+), 21 deletions(-)
> >  rename Doxyfile => Doxyfile.in (93%)
> >
> > --
> > 2.28.0
> >
> 
> Thanks for sending those! I guess I don't see any of the warnings you
> mention because doxygen on my laptop is too old (1.8.13)?
> 

For reference, I get some of the warnings addressed with doxygen 1.8.17
in my setup.
I don't get the a4wide (patch 3) so that might be new in 1.8.18, or
otherwise dependent on setup??

Either way, it would be useful for the patch to mention what version
of doxygen is being targetted so everyone is on the same page.

Cheers,
Kent.

Re: [libgpiod] [PATCH 0/5] Documentation improvements

[Alexander Stein]

Am Dienstag, 11. August 2020, 03:39:50 CEST schrieb Kent Gibson:
> On Mon, Aug 10, 2020 at 06:49:21PM +0200, Bartosz Golaszewski wrote:
> > On Sat, Aug 8, 2020 at 12:06 PM Alexander Stein
> > <alexander.stein@mailbox.org> wrote:
> > >
> > > Hey,
> > > this changeset improves the document generation by reducing warnings
> > > as well as supporting building doc out of tree now.
> > >
> > > Alexander Stein (5):
> > >   doc: Fix doxygen warnings
> > >   doc: Use autotoolized Doxyfile
> > >   doc: Fix doxygen warning
> > >   doc: Remove obsolete PERL_PATH
> > >   doc: Add @file to headers
> > >
> > >  .gitignore              |  1 +
> > >  Doxyfile => Doxyfile.in |  8 ++++----
> > >  Makefile.am             |  4 +---
> > >  bindings/cxx/gpiod.hpp  |  6 +++++-
> > >  configure.ac            |  1 +
> > >  include/gpiod.h         | 30 +++++++++++++++++-------------
> > >  6 files changed, 29 insertions(+), 21 deletions(-)
> > >  rename Doxyfile => Doxyfile.in (93%)
> > >
> > > --
> > > 2.28.0
> > >
> > 
> > Thanks for sending those! I guess I don't see any of the warnings you
> > mention because doxygen on my laptop is too old (1.8.13)?
> > 
> 
> For reference, I get some of the warnings addressed with doxygen 1.8.17
> in my setup.
> I don't get the a4wide (patch 3) so that might be new in 1.8.18, or
> otherwise dependent on setup??
> 
> Either way, it would be useful for the patch to mention what version
> of doxygen is being targetted so everyone is on the same page.

Yes, I'm on 1.8.18, current release for archlinux. You are right, I should
have mentioned it in the patch though, sorry aobut that.

Best regards,
Alexander

Re: [libgpiod] [PATCH 0/5] Documentation improvements

[Bartosz Golaszewski]

On Tue, Aug 11, 2020 at 8:24 PM Alexander Stein
<alexander.stein@mailbox.org> wrote:
>
> Am Dienstag, 11. August 2020, 03:39:50 CEST schrieb Kent Gibson:
> > On Mon, Aug 10, 2020 at 06:49:21PM +0200, Bartosz Golaszewski wrote:
> > > On Sat, Aug 8, 2020 at 12:06 PM Alexander Stein
> > > <alexander.stein@mailbox.org> wrote:
> > > >
> > > > Hey,
> > > > this changeset improves the document generation by reducing warnings
> > > > as well as supporting building doc out of tree now.
> > > >
> > > > Alexander Stein (5):
> > > >   doc: Fix doxygen warnings
> > > >   doc: Use autotoolized Doxyfile
> > > >   doc: Fix doxygen warning
> > > >   doc: Remove obsolete PERL_PATH
> > > >   doc: Add @file to headers
> > > >
> > > >  .gitignore              |  1 +
> > > >  Doxyfile => Doxyfile.in |  8 ++++----
> > > >  Makefile.am             |  4 +---
> > > >  bindings/cxx/gpiod.hpp  |  6 +++++-
> > > >  configure.ac            |  1 +
> > > >  include/gpiod.h         | 30 +++++++++++++++++-------------
> > > >  6 files changed, 29 insertions(+), 21 deletions(-)
> > > >  rename Doxyfile => Doxyfile.in (93%)
> > > >
> > > > --
> > > > 2.28.0
> > > >
> > >
> > > Thanks for sending those! I guess I don't see any of the warnings you
> > > mention because doxygen on my laptop is too old (1.8.13)?
> > >
> >
> > For reference, I get some of the warnings addressed with doxygen 1.8.17
> > in my setup.
> > I don't get the a4wide (patch 3) so that might be new in 1.8.18, or
> > otherwise dependent on setup??
> >
> > Either way, it would be useful for the patch to mention what version
> > of doxygen is being targetted so everyone is on the same page.
>
> Yes, I'm on 1.8.18, current release for archlinux. You are right, I should
> have mentioned it in the patch though, sorry aobut that.
>

No worries, I'll add this to the commit message when applying.

Bartosz

Re: [libgpiod] [PATCH 2/5] doc: Use autotoolized Doxyfile

[Bartosz Golaszewski]

On Sat, Aug 8, 2020 at 12:00 PM Alexander Stein
<alexander.stein@mailbox.org> wrote:
>
> This has several advantages:
> * More simplified Makefile.am
> * Actually used doxygen config is available as a file
> * Building doc out-of-tree is possible
>
> Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
> ---
>  .gitignore              | 1 +
>  Doxyfile => Doxyfile.in | 3 ++-
>  Makefile.am             | 4 +---
>  configure.ac            | 1 +
>  4 files changed, 5 insertions(+), 4 deletions(-)
>  rename Doxyfile => Doxyfile.in (95%)
>
> diff --git a/.gitignore b/.gitignore
> index 488d9d6..a77efde 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -10,6 +10,7 @@ doc
>  # autotools stuff
>  .deps/
>  .libs/
> +Doxyfile
>  Makefile
>  Makefile.in
>  aclocal.m4
> diff --git a/Doxyfile b/Doxyfile.in
> similarity index 95%
> rename from Doxyfile
> rename to Doxyfile.in
> index b194095..8c6d591 100644
> --- a/Doxyfile
> +++ b/Doxyfile.in
> @@ -10,6 +10,7 @@
>
>  # General configuration
>  PROJECT_NAME           = libgpiod
> +PROJECT_NUMBER         = @VERSION_STR@
>  OUTPUT_DIRECTORY       = doc
>  OUTPUT_LANGUAGE        = English
>  EXTRACT_ALL            = NO
> @@ -48,7 +49,7 @@ WARNINGS               = YES
>  WARN_IF_UNDOCUMENTED   = YES
>  WARN_FORMAT            =
>  WARN_LOGFILE           =
> -INPUT                  = include/gpiod.h
> +INPUT                  = @top_srcdir@/include/gpiod.h @top_srcdir@/bindings/cxx/gpiod.hpp
>  SOURCE_BROWSER         = YES
>  INLINE_SOURCES         = NO
>  REFERENCED_BY_RELATION = YES
> diff --git a/Makefile.am b/Makefile.am
> index d3f57b2..72e6a25 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -29,9 +29,7 @@ SUBDIRS += bindings
>  if HAS_DOXYGEN
>
>  doc:
> -       @(cat Doxyfile; \
> -               echo PROJECT_NUMBER = $(VERSION_STR); \
> -               echo INPUT += bindings/cxx/gpiod.hpp) | doxygen -
> +       @doxygen Doxyfile

This needs a dependency on Doxyfile in the Makefile or it won't work
if the generated Doxyfile is removed after .configure. I'll fix it in
the tree.

Bart

>  .PHONY: doc
>
>  clean-local:
> diff --git a/configure.ac b/configure.ac
> index 008499d..c2d9f99 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -207,6 +207,7 @@ if test "x$has_doxygen" = xfalse
>  then
>         AC_MSG_NOTICE([doxygen not found - documentation cannot be generated])
>  fi
> +AM_COND_IF([HAS_DOXYGEN], [AC_CONFIG_FILES([Doxyfile])])
>
>  if test "x$cross_compiling" = xno
>  then
> --
> 2.28.0
>