[libnfnetlink,0/1] Minimally resurrect doxygen documentation
mbox series

Message ID 20191014020223.21757-1-duncan_roe@optusnet.com.au
Headers show
Series
  • Minimally resurrect doxygen documentation
Related show

Message

Duncan Roe Oct. 14, 2019, 2:02 a.m. UTC
libnfnetlink has good doxygen documentation but there was no output when
doxygen was run.

Patch 1/1 fixes that,
but on rebuilding there were a number warnings of the form:

right-hand operand of comma expression has no effect [-Wunused-value]

*This was not introduced by patch 1/1*

Instead, it is caused by the definition of "prefetch" in include/linux_list.h:

 #define prefetch(x) 1

the Linux kernel has:

 #define prefetch(x) __builtin_prefetch(x)

I see 3 ways to get back to a clean compile:

1. Suppress the warnings with a pragma

2. Reinstate the Linux definition of prefetch

3. Expunge prefetch from the header file

I have made all 3, please indicate which one you'd like.

1. & 2. are 1-liners while 3. is multiline.

3. allows of extra simplifications, such as defining a macro in a single
line or fewer lines than before. In some places I could also delete the fragment
"&& ({ 1;})".


Duncan Roe (1):
  src: Minimally resurrect doxygen documentation

 configure.ac         |   2 +-
 doxygen.cfg.in       | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux_list.h |   9 +++
 src/iftable.c        |   9 +++
 src/libnfnetlink.c   |  17 ++++-
 5 files changed, 215 insertions(+), 2 deletions(-)
 create mode 100644 doxygen.cfg.in

Comments

Duncan Roe Oct. 15, 2019, 10:52 p.m. UTC | #1
Hi Pablo,

On Mon, Oct 14, 2019 at 01:02:22PM +1100, Duncan Roe wrote:
> libnfnetlink has good doxygen documentation but there was no output when
> doxygen was run.
>
> Patch 1/1 fixes that,
> but on rebuilding there were a number warnings of the form:
>
> right-hand operand of comma expression has no effect [-Wunused-value]
>
> *This was not introduced by patch 1/1*
>
> Instead, it is caused by the definition of "prefetch" in include/linux_list.h:
>
>  #define prefetch(x) 1
>
> the Linux kernel has:
>
>  #define prefetch(x) __builtin_prefetch(x)
>
> I see 3 ways to get back to a clean compile:
>
> 1. Suppress the warnings with a pragma
>
> 2. Reinstate the Linux definition of prefetch
>
> 3. Expunge prefetch from the header file
>
> I have made all 3, please indicate which one you'd like.
>
> 1. & 2. are 1-liners while 3. is multiline.
>
> 3. allows of extra simplifications, such as defining a macro in a single
> line or fewer lines than before. In some places I could also delete the fragment
> "&& ({ 1;})".
>
>
> Duncan Roe (1):
>   src: Minimally resurrect doxygen documentation
>
>  configure.ac         |   2 +-
>  doxygen.cfg.in       | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  include/linux_list.h |   9 +++
>  src/iftable.c        |   9 +++
>  src/libnfnetlink.c   |  17 ++++-
>  5 files changed, 215 insertions(+), 2 deletions(-)
>  create mode 100644 doxygen.cfg.in
>
> --
> 2.14.5
>
Any feedback on this?

Exposing the documentation would be uncontroversial surely?

In regard to compiler warnings, alternative 1 entails least effort to review,
since the code remains unchanged.

Cheers ... Duncan.