[PATCH libnfnetlink 0/1] Minimally resurrect doxygen documentation

[PATCH libnfnetlink 0/1] Minimally resurrect doxygen documentation

[Duncan Roe]

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

[PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Duncan Roe]

The documentation was written in the days before doxygen required groups or even
doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
file, encompassing pretty-much the whole file.

Also add a tiny \mainpage.

Added:

 doxygen.cfg.in: Same as for libmnl except FILE_PATTERNS = *.c linux_list.h

Updated:

 configure.ac: Create doxygen.cfg

 include/linux_list.h: Add defgroup

 src/iftable.c: Add defgroup

 src/libnfnetlink.c: Add mainpage and defgroup

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 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

diff --git a/configure.ac b/configure.ac
index b979772..922ec09 100644
--- a/configure.ac
+++ b/configure.ac
@@ -28,6 +28,6 @@ dnl--------------------------------
 
 
 dnl Output the makefile
-AC_CONFIG_FILES([Makefile src/Makefile include/Makefile
+AC_CONFIG_FILES([Makefile src/Makefile include/Makefile doxygen.cfg
 	include/libnfnetlink/Makefile utils/Makefile libnfnetlink.pc])
 AC_OUTPUT
diff --git a/doxygen.cfg.in b/doxygen.cfg.in
new file mode 100644
index 0000000..43c8138
--- /dev/null
+++ b/doxygen.cfg.in
@@ -0,0 +1,180 @@
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = @PACKAGE@
+PROJECT_NUMBER         = @VERSION@
+OUTPUT_DIRECTORY       = doxygen
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = 
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = NO
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+FILE_VERSION_FILTER    = 
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+INPUT                  = .
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c linux_list.h
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = */.git/* .*.d
+EXCLUDE_SYMBOLS        = EXPORT_SYMBOL
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = 
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_STYLESHEET        = 
+GENERATE_HTMLHELP      = NO
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+HTML_DYNAMIC_SECTIONS  = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+GENERATE_MAN           = YES
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = YES
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+SEARCHENGINE           = NO
diff --git a/include/linux_list.h b/include/linux_list.h
index de182a4..d296cfa 100644
--- a/include/linux_list.h
+++ b/include/linux_list.h
@@ -3,6 +3,11 @@
 
 #include <stddef.h>
 
+/**
+ * \defgroup linux_list Items defined in linux_list.h
+ * @{
+ */
+
 #undef offsetof
 #define offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)
 
@@ -724,4 +729,8 @@ static inline void hlist_add_after(struct hlist_node *n,
 		({ tpos = hlist_entry(pos, typeof(*tpos), member); 1;}); \
 	     pos = pos->next, ({ smp_read_barrier_depends(); 0; }) )
 
+/**
+ * @}
+ */
+
 #endif
diff --git a/src/iftable.c b/src/iftable.c
index 157f97b..6d1d135 100644
--- a/src/iftable.c
+++ b/src/iftable.c
@@ -24,6 +24,11 @@
 #include "rtnl.h"
 #include "linux_list.h"
 
+/**
+ * \defgroup iftable Functions in iftable.c
+ * @{
+ */
+
 struct ifindex_node {
 	struct list_head head;
 
@@ -333,3 +338,7 @@ int nlif_fd(struct nlif_handle *h)
 
 	return -1;
 }
+
+/**
+ * @}
+ */
diff --git a/src/libnfnetlink.c b/src/libnfnetlink.c
index df57533..3db21e0 100644
--- a/src/libnfnetlink.c
+++ b/src/libnfnetlink.c
@@ -52,6 +52,18 @@
 
 #include <libnfnetlink/libnfnetlink.h>
 
+/**
+ * \mainpage
+ *
+ * libnfnetlink is the bottom-level communication between the kernel and
+ * userspace
+ */
+
+/**
+ * \defgroup libnfnetlink Functions in libnfnetlink.c
+ * @{
+ */
+
 #ifndef NETLINK_ADD_MEMBERSHIP
 #define NETLINK_ADD_MEMBERSHIP 1
 #endif
@@ -60,7 +72,6 @@
 #define SOL_NETLINK 270
 #endif
 
-
 #define nfnl_error(format, args...) \
 	fprintf(stderr, "%s: " format "\n", __FUNCTION__, ## args)
 
@@ -1572,3 +1583,7 @@ int nfnl_query(struct nfnl_handle *h, struct nlmsghdr *nlh)
 
 	return nfnl_catch(h);
 }
+
+/**
+ * @}
+ */
-- 
2.14.5

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Pablo Neira Ayuso]

On Mon, Oct 14, 2019 at 01:02:23PM +1100, Duncan Roe wrote:
> The documentation was written in the days before doxygen required groups or even
> doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> file, encompassing pretty-much the whole file.
> 
> Also add a tiny \mainpage.
> 
> Added:
> 
>  doxygen.cfg.in: Same as for libmnl except FILE_PATTERNS = *.c linux_list.h
> 
> Updated:
> 
>  configure.ac: Create doxygen.cfg
> 
>  include/linux_list.h: Add defgroup
> 
>  src/iftable.c: Add defgroup
> 
>  src/libnfnetlink.c: Add mainpage and defgroup

I'm ambivalent about this, it's been up on the table for a while.

This library is rather old, and new applications should probably
be based instead used libmnl, which is a better choice.

Did you already queue patches to make documentation for libnfnetlink
locally there? I would like not to discourage you in your efforts to
help us improve documentation, which is always extremely useful for
everyone.

Let me know, thanks.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Duncan Roe]

On Wed, Oct 23, 2019 at 01:13:46PM +0200, Pablo Neira Ayuso wrote:
> On Mon, Oct 14, 2019 at 01:02:23PM +1100, Duncan Roe wrote:
> > The documentation was written in the days before doxygen required groups or even
> > doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> > file, encompassing pretty-much the whole file.
> >
> > Also add a tiny \mainpage.
> >
> > Added:
> >
> >  doxygen.cfg.in: Same as for libmnl except FILE_PATTERNS = *.c linux_list.h
> >
> > Updated:
> >
> >  configure.ac: Create doxygen.cfg
> >
> >  include/linux_list.h: Add defgroup
> >
> >  src/iftable.c: Add defgroup
> >
> >  src/libnfnetlink.c: Add mainpage and defgroup
>
> I'm ambivalent about this, it's been up on the table for a while.
>
> This library is rather old, and new applications should probably
> be based instead used libmnl, which is a better choice.
>
> Did you already queue patches to make documentation for libnfnetlink
> locally there? I would like not to discourage you in your efforts to
> help us improve documentation, which is always extremely useful for
> everyone.
>
> Let me know, thanks.

Very timely of you to ask.

Just this morning I was going to get back into libnetfilter_queue documentation,
starting with the other 2 verdict helpers.

But I ran into a conundrum with nfq_nlmsg_verdict_put_mark (the one I didn't
use). It's a 1-liner (in src/nlmsg.c):

> 56  mnl_attr_put_u32(nlh, NFQA_MARK, htonl(mark));

But examples/nf-queue.c has an example to set the connmark which doesn't use
nfq_nlmsg_verdict_put_mark()

Instead it has this line:

> 52  mnl_attr_put_u32(nlh, CTA_MARK, htonl(42));

The trouble is, NFQA_MARK *is different from* CTA_MARK. NFQA_MARK is 3, while
CTA_MARK is 8.

At this point, I felt I did not understand the software well enough to be able
to document it further. If you could shed some light on this apparent
disrcepancy, it might restore my self-confidence sufficiently that I can
continue documenting.

Cheers ... Duncan.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Jeremy Sowden]

[-- Attachment #1: Type: text/plain, Size: 2157 bytes --]

On 2019-10-24, at 02:12:05 +1100, Duncan Roe wrote:
> Just this morning I was going to get back into libnetfilter_queue
> documentation, starting with the other 2 verdict helpers.
>
> But I ran into a conundrum with nfq_nlmsg_verdict_put_mark (the one I
> didn't use). It's a 1-liner (in src/nlmsg.c):
>
> > 56  mnl_attr_put_u32(nlh, NFQA_MARK, htonl(mark));
>
> But examples/nf-queue.c has an example to set the connmark which
> doesn't use nfq_nlmsg_verdict_put_mark()
>
> Instead it has this line:
>
> > 52  mnl_attr_put_u32(nlh, CTA_MARK, htonl(42));
>
> The trouble is, NFQA_MARK *is different from* CTA_MARK. NFQA_MARK is
> 3, while CTA_MARK is 8.
>
> At this point, I felt I did not understand the software well enough to
> be able to document it further. If you could shed some light on this
> apparent disrcepancy, it might restore my self-confidence sufficiently
> that I can continue documenting.

`NFQA_MARK` is used for setting the `nfmark`; `CTA_MARK` is used for
setting the `ctmark`.  Here are the relevant stanzas from the NF
Kconfig:

  config NETFILTER_XT_MARK
    tristate 'nfmark target and match support'
    default m if NETFILTER_ADVANCED=n
    ---help---
    This option adds the "MARK" target and "mark" match.

    Netfilter mark matching allows you to match packets based on the
    "nfmark" value in the packet.
    The target allows you to create rules in the "mangle" table which
    alter the netfilter mark (nfmark) field associated with the packet.

    Prior to routing, the nfmark can influence the routing method and
    can also be used by other subsystems to change their behavior.

  config NETFILTER_XT_CONNMARK
    tristate 'ctmark target and match support'
    depends on NF_CONNTRACK
    depends on NETFILTER_ADVANCED
    select NF_CONNTRACK_MARK
    ---help---
    This option adds the "CONNMARK" target and "connmark" match.

    Netfilter allows you to store a mark value per connection (a.k.a.
    ctmark), similarly to the packet mark (nfmark). Using this target
    and match, you can set and match on this mark.

`nfq_nlmsg_verdict_put_mark` sets an `nfmark` whereas the example is
setting a `ctmark`.

J.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Pablo Neira Ayuso]

On Thu, Oct 24, 2019 at 02:12:05AM +1100, Duncan Roe wrote:
> On Wed, Oct 23, 2019 at 01:13:46PM +0200, Pablo Neira Ayuso wrote:
> > On Mon, Oct 14, 2019 at 01:02:23PM +1100, Duncan Roe wrote:
> > > The documentation was written in the days before doxygen required groups or even
> > > doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> > > file, encompassing pretty-much the whole file.
> > >
> > > Also add a tiny \mainpage.
> > >
> > > Added:
> > >
> > >  doxygen.cfg.in: Same as for libmnl except FILE_PATTERNS = *.c linux_list.h
> > >
> > > Updated:
> > >
> > >  configure.ac: Create doxygen.cfg
> > >
> > >  include/linux_list.h: Add defgroup
> > >
> > >  src/iftable.c: Add defgroup
> > >
> > >  src/libnfnetlink.c: Add mainpage and defgroup
> >
> > I'm ambivalent about this, it's been up on the table for a while.
> >
> > This library is rather old, and new applications should probably
> > be based instead used libmnl, which is a better choice.
> >
> > Did you already queue patches to make documentation for libnfnetlink
> > locally there? I would like not to discourage you in your efforts to
> > help us improve documentation, which is always extremely useful for
> > everyone.
> >
> > Let me know, thanks.
> 
> Very timely of you to ask.
> 
> Just this morning I was going to get back into libnetfilter_queue documentation,
> starting with the other 2 verdict helpers.
> 
> But I ran into a conundrum with nfq_nlmsg_verdict_put_mark (the one I didn't
> use). It's a 1-liner (in src/nlmsg.c):
> 
> > 56  mnl_attr_put_u32(nlh, NFQA_MARK, htonl(mark));
> 
> But examples/nf-queue.c has an example to set the connmark which doesn't use
> nfq_nlmsg_verdict_put_mark()
> 
> Instead it has this line:
> 
> > 52  mnl_attr_put_u32(nlh, CTA_MARK, htonl(42));
> 
> The trouble is, NFQA_MARK *is different from* CTA_MARK. NFQA_MARK is 3, while
> CTA_MARK is 8.
> 
> At this point, I felt I did not understand the software well enough to be able
> to document it further. If you could shed some light on this apparent
> disrcepancy, it might restore my self-confidence sufficiently that I can
> continue documenting.

The idea is that the new libnetfilter_queue API provides a set of
helpers for libmnl. Hence, you have access to the netlink socket API
and you use the helpers to build the netlink message.

The netlink sockets allows you to communicate userspace with the
corresponding kernel subsystem. The message you send to the kernel is
composed of two headers, one is the struct nlmsghdr (netlink header)
and then it follows the nfnl header. The payload of the netlink
message is composite of Type-Length-Value (TLV) attributes.

Therefore:

        mnl_attr_put_u32(nlh, CTA_MARK, htonl(42));

is adding the TLV that represents the conntrack mark.

The value is in network-byte-order for historical reasons, there were
an original effort to place netlink message on the network wire, but
at the end of the day this was not used in practise.

So the new libnetfilter_queue API is more low-level, in the sense that
you have more control on netlink aspects, such as the socket
initialization and the message building / parsing.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Duncan Roe]

On Wed, Oct 23, 2019 at 01:13:46PM +0200, Pablo Neira Ayuso wrote:
> On Mon, Oct 14, 2019 at 01:02:23PM +1100, Duncan Roe wrote:
> > The documentation was written in the days before doxygen required groups or even
> > doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> > file, encompassing pretty-much the whole file.
> >
[...]
> >
>
> I'm ambivalent about this, it's been up on the table for a while.
>
> This library is rather old, and new applications should probably
> be based instead used libmnl, which is a better choice.
>
The thing is, the Deprecated functions in libnetfilter_queue are much better
documented than the newer functions and that documentation refers to
libnfnetlink functions.

So I think that while the deprecated functions are documented, you should really
have documentation for the old library they use.

BTW, ldd of my app shows libnfnetlink.so although it doesn't use any deprecated
functions. Is that expected?

Cheers ... Duncan.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Pablo Neira Ayuso]

On Thu, Oct 24, 2019 at 02:31:42AM +1100, Duncan Roe wrote:
> On Wed, Oct 23, 2019 at 01:13:46PM +0200, Pablo Neira Ayuso wrote:
> > On Mon, Oct 14, 2019 at 01:02:23PM +1100, Duncan Roe wrote:
> > > The documentation was written in the days before doxygen required groups or even
> > > doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> > > file, encompassing pretty-much the whole file.
> > >
> [...]
> > >
> >
> > I'm ambivalent about this, it's been up on the table for a while.
> >
> > This library is rather old, and new applications should probably
> > be based instead used libmnl, which is a better choice.
> >
> The thing is, the Deprecated functions in libnetfilter_queue are much better
> documented than the newer functions and that documentation refers to
> libnfnetlink functions.

Would you help me get better the documentation for the new
libnetfilter_queue API? I'll be trying to address your questions
timely in case you decide to enroll in such endeavor.

> So I think that while the deprecated functions are documented, you should really
> have documentation for the old library they use.

Are you refering to libnfnetlink or libnetfilter_queue in this case?
If you insist on documenting libnfnetlink, I'll be fine with it, no
worries.

> BTW, ldd of my app shows libnfnetlink.so although it doesn't use any deprecated
> functions. Is that expected?

Yes, there is still code in the libraries that refer to libnfnetlink.
Replacing some of that code should be feasible via libmnl, it is a
task that has been in my TODO list for long time. There's always
something with more priority in the queue.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Duncan Roe]

Hi Pablo,

On Wed, Oct 23, 2019 at 10:48:36PM +0200, Pablo Neira Ayuso wrote:
> On Thu, Oct 24, 2019 at 02:31:42AM +1100, Duncan Roe wrote:
> > On Wed, Oct 23, 2019 at 01:13:46PM +0200, Pablo Neira Ayuso wrote:
> > > On Mon, Oct 14, 2019 at 01:02:23PM +1100, Duncan Roe wrote:
> > > > The documentation was written in the days before doxygen required groups or even
> > > > doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> > > > file, encompassing pretty-much the whole file.
> > > >
> > [...]
> > > >
> > >
> > > I'm ambivalent about this, it's been up on the table for a while.
> > >
> > > This library is rather old, and new applications should probably
> > > be based instead used libmnl, which is a better choice.
> > >
> > The thing is, the Deprecated functions in libnetfilter_queue are much better
> > documented than the newer functions and that documentation refers to
> > libnfnetlink functions.
>
> Would you help me get better the documentation for the new
> libnetfilter_queue API? I'll be trying to address your questions
> timely in case you decide to enroll in such endeavor.

OK I will take that on as a project.
>
> > So I think that while the deprecated functions are documented, you should really
> > have documentation for the old library they use.
>
> Are you refering to libnfnetlink or libnetfilter_queue in this case?

libnetfilter_queue

> If you insist on documenting libnfnetlink, I'll be fine with it, no
> worries.

Yes I insist. LMK which compiler warning fix you'd like (if any)
>
> > BTW, ldd of my app shows libnfnetlink.so although it doesn't use any deprecated
> > functions. Is that expected?
>
> Yes, there is still code in the libraries that refer to libnfnetlink.
> Replacing some of that code should be feasible via libmnl, it is a
> task that has been in my TODO list for long time. There's always
> something with more priority in the queue.

Cheers ... Duncan.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Duncan Roe]

On Wed, Oct 23, 2019 at 10:48:36PM +0200, Pablo Neira Ayuso wrote:
> On Thu, Oct 24, 2019 at 02:31:42AM +1100, Duncan Roe wrote:
> > BTW, ldd of my app shows libnfnetlink.so although it doesn't use any deprecated
> > functions. Is that expected?
> 
> Yes, there is still code in the libraries that refer to libnfnetlink.
> Replacing some of that code should be feasible via libmnl, it is a
> task that has been in my TODO list for long time. There's always
> something with more priority in the queue.

Using *nm -D* (dynamic symbols) I see
 - libmnl.so: no U (undefined) symbols satisfied by libnfnetlink.so
 - nfq (my app): no U symbols satisfied by libnfnetlink.so
 - libnetfilter_queue.so: many U symbols satisfied by libnfnetlink.so
Only way to tell whether the libnfnetlink.so references in libnetfilter_queue.so
are confined to the deprecated functions would be to do a build without them.
If that eliminates libnfnetlink references, then maybe we could think about a
configure option to not build them (also excluding them from the doco).
But that's for another day - I'll get back to libnetfilter_queue doco for now.

Cheers ... Duncan.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Pablo Neira Ayuso]

On Sat, Oct 26, 2019 at 06:40:00PM +1100, Duncan Roe wrote:
> On Wed, Oct 23, 2019 at 10:48:36PM +0200, Pablo Neira Ayuso wrote:
> > On Thu, Oct 24, 2019 at 02:31:42AM +1100, Duncan Roe wrote:
> > > BTW, ldd of my app shows libnfnetlink.so although it doesn't use any deprecated
> > > functions. Is that expected?
> > 
> > Yes, there is still code in the libraries that refer to libnfnetlink.
> > Replacing some of that code should be feasible via libmnl, it is a
> > task that has been in my TODO list for long time. There's always
> > something with more priority in the queue.
> 
> Using *nm -D* (dynamic symbols) I see
>  - libmnl.so: no U (undefined) symbols satisfied by libnfnetlink.so
>  - nfq (my app): no U symbols satisfied by libnfnetlink.so
>  - libnetfilter_queue.so: many U symbols satisfied by libnfnetlink.so
> Only way to tell whether the libnfnetlink.so references in libnetfilter_queue.so
> are confined to the deprecated functions would be to do a build without them.
> If that eliminates libnfnetlink references, then maybe we could think about a
> configure option to not build them (also excluding them from the doco).

Apparently, there are many people using this old libnetfilter_queue
API, we cannot get rid of it. We could though explore using libmnl
instead of libnfnetlink from the old libnetfilter_queue API
implementation.

> But that's for another day - I'll get back to libnetfilter_queue doco for now.

Agreed.

Re: [PATCH libnfnetlink 1/1] src: Minimally resurrect doxygen documentation

[Duncan Roe]

On Wed, Oct 23, 2019 at 01:13:46PM +0200, Pablo Neira Ayuso wrote:
> On Mon, Oct 14, 2019 at 01:02:23PM +1100, Duncan Roe wrote:
> > The documentation was written in the days before doxygen required groups or even
> > doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> > file, encompassing pretty-much the whole file.
> >
> > Also add a tiny \mainpage.
> >
[...]
>
> I'm ambivalent about this, it's been up on the table for a while.
>
> This library is rather old, and new applications should probably
> be based instead used libmnl, which is a better choice.

I'm sending a v2 which makes this abundantly clear
>
> Did you already queue patches to make documentation for libnfnetlink
> locally there? I would like not to discourage you in your efforts to
> help us improve documentation, which is always extremely useful for
> everyone.

No, I'm concentrating on libnetfilter_queue from now on.

Cheers ... Duncan.

[PATCH libnfnetlink v2 0/2] Minimally resurrect doxygen documentation

[Duncan Roe]

The documentation was written in the days before doxygen required groups or even
doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
file, encompassing pretty-much the whole file.

Also add a tiny \mainpage.

--
v2: main page and function pages make it clear to use libmnl for new apps

Duncan Roe (2):
  Minimally resurrect doxygen documentation
  Make it clear that this library is deprecated

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

-- 
2.14.5

[PATCH libnfnetlink v2 1/2] Minimally resurrect doxygen documentation

[Duncan Roe]

The documentation was written in the days before doxygen required groups or even
doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
file, encompassing pretty-much the whole file.

Also add a tiny \mainpage.

Added:

 doxygen.cfg.in: Same as for libmnl except FILE_PATTERNS = *.c linux_list.h

Updated:

 configure.ac: Create doxygen.cfg

 include/linux_list.h: Add defgroup

 src/iftable.c: Add defgroup

 src/libnfnetlink.c: Add mainpage and defgroup
---
 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

diff --git a/configure.ac b/configure.ac
index b979772..922ec09 100644
--- a/configure.ac
+++ b/configure.ac
@@ -28,6 +28,6 @@ dnl--------------------------------
 
 
 dnl Output the makefile
-AC_CONFIG_FILES([Makefile src/Makefile include/Makefile
+AC_CONFIG_FILES([Makefile src/Makefile include/Makefile doxygen.cfg
 	include/libnfnetlink/Makefile utils/Makefile libnfnetlink.pc])
 AC_OUTPUT
diff --git a/doxygen.cfg.in b/doxygen.cfg.in
new file mode 100644
index 0000000..43c8138
--- /dev/null
+++ b/doxygen.cfg.in
@@ -0,0 +1,180 @@
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = @PACKAGE@
+PROJECT_NUMBER         = @VERSION@
+OUTPUT_DIRECTORY       = doxygen
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = 
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = NO
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+FILE_VERSION_FILTER    = 
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+INPUT                  = .
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c linux_list.h
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = */.git/* .*.d
+EXCLUDE_SYMBOLS        = EXPORT_SYMBOL
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = 
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_STYLESHEET        = 
+GENERATE_HTMLHELP      = NO
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+HTML_DYNAMIC_SECTIONS  = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+GENERATE_MAN           = YES
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = YES
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+SEARCHENGINE           = NO
diff --git a/include/linux_list.h b/include/linux_list.h
index de182a4..d296cfa 100644
--- a/include/linux_list.h
+++ b/include/linux_list.h
@@ -3,6 +3,11 @@
 
 #include <stddef.h>
 
+/**
+ * \defgroup linux_list Items defined in linux_list.h
+ * @{
+ */
+
 #undef offsetof
 #define offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)
 
@@ -724,4 +729,8 @@ static inline void hlist_add_after(struct hlist_node *n,
 		({ tpos = hlist_entry(pos, typeof(*tpos), member); 1;}); \
 	     pos = pos->next, ({ smp_read_barrier_depends(); 0; }) )
 
+/**
+ * @}
+ */
+
 #endif
diff --git a/src/iftable.c b/src/iftable.c
index 157f97b..6d1d135 100644
--- a/src/iftable.c
+++ b/src/iftable.c
@@ -24,6 +24,11 @@
 #include "rtnl.h"
 #include "linux_list.h"
 
+/**
+ * \defgroup iftable Functions in iftable.c
+ * @{
+ */
+
 struct ifindex_node {
 	struct list_head head;
 
@@ -333,3 +338,7 @@ int nlif_fd(struct nlif_handle *h)
 
 	return -1;
 }
+
+/**
+ * @}
+ */
diff --git a/src/libnfnetlink.c b/src/libnfnetlink.c
index df57533..3db21e0 100644
--- a/src/libnfnetlink.c
+++ b/src/libnfnetlink.c
@@ -52,6 +52,18 @@
 
 #include <libnfnetlink/libnfnetlink.h>
 
+/**
+ * \mainpage
+ *
+ * libnfnetlink is the bottom-level communication between the kernel and
+ * userspace
+ */
+
+/**
+ * \defgroup libnfnetlink Functions in libnfnetlink.c
+ * @{
+ */
+
 #ifndef NETLINK_ADD_MEMBERSHIP
 #define NETLINK_ADD_MEMBERSHIP 1
 #endif
@@ -60,7 +72,6 @@
 #define SOL_NETLINK 270
 #endif
 
-
 #define nfnl_error(format, args...) \
 	fprintf(stderr, "%s: " format "\n", __FUNCTION__, ## args)
 
@@ -1572,3 +1583,7 @@ int nfnl_query(struct nfnl_handle *h, struct nlmsghdr *nlh)
 
 	return nfnl_catch(h);
 }
+
+/**
+ * @}
+ */
-- 
2.14.5

[PATCH libnfnetlink v2 2/2] Make it clear that this library is deprecated

[Duncan Roe]

 src/iftable.c: Update group description

 src/libnfnetlink.c: - Re-work main page (which was based on the misconception
                       that this library always gets used)
                     - Update group description
---
 src/iftable.c      |  6 +++++-
 src/libnfnetlink.c | 17 ++++++++++++++---
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/src/iftable.c b/src/iftable.c
index 6d1d135..aab59b3 100644
--- a/src/iftable.c
+++ b/src/iftable.c
@@ -25,7 +25,11 @@
 #include "linux_list.h"
 
 /**
- * \defgroup iftable Functions in iftable.c
+ * \defgroup iftable Functions in iftable.c [DEPRECATED]
+ * This documentation is provided for the benefit of maintainers of legacy code.
+ *
+ * New applications should use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
  * @{
  */
 
diff --git a/src/libnfnetlink.c b/src/libnfnetlink.c
index 3db21e0..1cb6a82 100644
--- a/src/libnfnetlink.c
+++ b/src/libnfnetlink.c
@@ -55,12 +55,23 @@
 /**
  * \mainpage
  *
- * libnfnetlink is the bottom-level communication between the kernel and
- * userspace
+ * Deprecated
+ * ---
+ * New applications should use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
+ *
+ * [libnetfilter_queue]
+ * (https://netfilter.org/projects/libnetfilter_queue/doxygen/html/)
+ * now provides a set of helpers for libmnl, in addition to those it provides
+ * for libnfnetlink (which are now deprecated).
  */
 
 /**
- * \defgroup libnfnetlink Functions in libnfnetlink.c
+ * \defgroup libnfnetlink Functions in libnfnetlink.c [DEPRECATED]
+ * This documentation is provided for the benefit of maintainers of legacy code.
+ *
+ * New applications should use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
  * @{
  */
 
-- 
2.14.5

[PATCH libnfnetlink v3 0/2] Minimally resurrect doxygen documentation

[Duncan Roe]

The documentation was written in the days before doxygen required groups or even
doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
file, encompassing pretty-much the whole file.

Also add a tiny \mainpage.

--
v2: main page and function pages make it clear to use libmnl for new apps
v3: add Signed-off-by

Duncan Roe (2):
  Minimally resurrect doxygen documentation
  Make it clear that this library is deprecated

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

-- 
2.14.5

[PATCH libnfnetlink v3 1/2] Minimally resurrect doxygen documentation

[Duncan Roe]

The documentation was written in the days before doxygen required groups or even
doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
file, encompassing pretty-much the whole file.

Also add a tiny \mainpage.

Added:

 doxygen.cfg.in: Same as for libmnl except FILE_PATTERNS = *.c linux_list.h

Updated:

 configure.ac: Create doxygen.cfg

 include/linux_list.h: Add defgroup

 src/iftable.c: Add defgroup

 src/libnfnetlink.c: Add mainpage and defgroup

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 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

diff --git a/configure.ac b/configure.ac
index b979772..922ec09 100644
--- a/configure.ac
+++ b/configure.ac
@@ -28,6 +28,6 @@ dnl--------------------------------
 
 
 dnl Output the makefile
-AC_CONFIG_FILES([Makefile src/Makefile include/Makefile
+AC_CONFIG_FILES([Makefile src/Makefile include/Makefile doxygen.cfg
 	include/libnfnetlink/Makefile utils/Makefile libnfnetlink.pc])
 AC_OUTPUT
diff --git a/doxygen.cfg.in b/doxygen.cfg.in
new file mode 100644
index 0000000..43c8138
--- /dev/null
+++ b/doxygen.cfg.in
@@ -0,0 +1,180 @@
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = @PACKAGE@
+PROJECT_NUMBER         = @VERSION@
+OUTPUT_DIRECTORY       = doxygen
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = 
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = NO
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+FILE_VERSION_FILTER    = 
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+INPUT                  = .
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c linux_list.h
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = */.git/* .*.d
+EXCLUDE_SYMBOLS        = EXPORT_SYMBOL
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = 
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_STYLESHEET        = 
+GENERATE_HTMLHELP      = NO
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+HTML_DYNAMIC_SECTIONS  = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+GENERATE_MAN           = YES
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = YES
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+SEARCHENGINE           = NO
diff --git a/include/linux_list.h b/include/linux_list.h
index de182a4..d296cfa 100644
--- a/include/linux_list.h
+++ b/include/linux_list.h
@@ -3,6 +3,11 @@
 
 #include <stddef.h>
 
+/**
+ * \defgroup linux_list Items defined in linux_list.h
+ * @{
+ */
+
 #undef offsetof
 #define offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)
 
@@ -724,4 +729,8 @@ static inline void hlist_add_after(struct hlist_node *n,
 		({ tpos = hlist_entry(pos, typeof(*tpos), member); 1;}); \
 	     pos = pos->next, ({ smp_read_barrier_depends(); 0; }) )
 
+/**
+ * @}
+ */
+
 #endif
diff --git a/src/iftable.c b/src/iftable.c
index 157f97b..6d1d135 100644
--- a/src/iftable.c
+++ b/src/iftable.c
@@ -24,6 +24,11 @@
 #include "rtnl.h"
 #include "linux_list.h"
 
+/**
+ * \defgroup iftable Functions in iftable.c
+ * @{
+ */
+
 struct ifindex_node {
 	struct list_head head;
 
@@ -333,3 +338,7 @@ int nlif_fd(struct nlif_handle *h)
 
 	return -1;
 }
+
+/**
+ * @}
+ */
diff --git a/src/libnfnetlink.c b/src/libnfnetlink.c
index df57533..3db21e0 100644
--- a/src/libnfnetlink.c
+++ b/src/libnfnetlink.c
@@ -52,6 +52,18 @@
 
 #include <libnfnetlink/libnfnetlink.h>
 
+/**
+ * \mainpage
+ *
+ * libnfnetlink is the bottom-level communication between the kernel and
+ * userspace
+ */
+
+/**
+ * \defgroup libnfnetlink Functions in libnfnetlink.c
+ * @{
+ */
+
 #ifndef NETLINK_ADD_MEMBERSHIP
 #define NETLINK_ADD_MEMBERSHIP 1
 #endif
@@ -60,7 +72,6 @@
 #define SOL_NETLINK 270
 #endif
 
-
 #define nfnl_error(format, args...) \
 	fprintf(stderr, "%s: " format "\n", __FUNCTION__, ## args)
 
@@ -1572,3 +1583,7 @@ int nfnl_query(struct nfnl_handle *h, struct nlmsghdr *nlh)
 
 	return nfnl_catch(h);
 }
+
+/**
+ * @}
+ */
-- 
2.14.5

Re: [PATCH libnfnetlink v3 1/2] Minimally resurrect doxygen documentation

[Pablo Neira Ayuso]

On Sun, Oct 27, 2019 at 07:49:06PM +1100, Duncan Roe wrote:
> The documentation was written in the days before doxygen required groups or even
> doxygen.cfg, so create doxygen.cfg.in and introduce one \defgroup per source
> file, encompassing pretty-much the whole file.
> 
> Also add a tiny \mainpage.
> 
> Added:
> 
>  doxygen.cfg.in: Same as for libmnl except FILE_PATTERNS = *.c linux_list.h
> 
> Updated:
> 
>  configure.ac: Create doxygen.cfg
> 
>  include/linux_list.h: Add defgroup
> 
>  src/iftable.c: Add defgroup
> 
>  src/libnfnetlink.c: Add mainpage and defgroup

Applied, thanks.

I have kept back include/linux_list.h, although this is offering the
linux list API in libnfnetlink, this was never intended to be the
purpose of this library, so I removed that part before applying.

[PATCH libnfnetlink v3 2/2] Make it clear that this library is deprecated

[Duncan Roe]

 src/iftable.c: Update group description

 src/libnfnetlink.c: - Re-work main page (which was based on the misconception
                       that this library always gets used)
                     - Update group description

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 src/iftable.c      |  6 +++++-
 src/libnfnetlink.c | 17 ++++++++++++++---
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/src/iftable.c b/src/iftable.c
index 6d1d135..aab59b3 100644
--- a/src/iftable.c
+++ b/src/iftable.c
@@ -25,7 +25,11 @@
 #include "linux_list.h"
 
 /**
- * \defgroup iftable Functions in iftable.c
+ * \defgroup iftable Functions in iftable.c [DEPRECATED]
+ * This documentation is provided for the benefit of maintainers of legacy code.
+ *
+ * New applications should use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
  * @{
  */
 
diff --git a/src/libnfnetlink.c b/src/libnfnetlink.c
index 3db21e0..1cb6a82 100644
--- a/src/libnfnetlink.c
+++ b/src/libnfnetlink.c
@@ -55,12 +55,23 @@
 /**
  * \mainpage
  *
- * libnfnetlink is the bottom-level communication between the kernel and
- * userspace
+ * Deprecated
+ * ---
+ * New applications should use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
+ *
+ * [libnetfilter_queue]
+ * (https://netfilter.org/projects/libnetfilter_queue/doxygen/html/)
+ * now provides a set of helpers for libmnl, in addition to those it provides
+ * for libnfnetlink (which are now deprecated).
  */
 
 /**
- * \defgroup libnfnetlink Functions in libnfnetlink.c
+ * \defgroup libnfnetlink Functions in libnfnetlink.c [DEPRECATED]
+ * This documentation is provided for the benefit of maintainers of legacy code.
+ *
+ * New applications should use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
  * @{
  */
 
-- 
2.14.5

Re: [PATCH libnfnetlink v3 2/2] Make it clear that this library is deprecated

[Pablo Neira Ayuso]

On Sun, Oct 27, 2019 at 07:49:07PM +1100, Duncan Roe wrote:
>  src/iftable.c: Update group description
> 
>  src/libnfnetlink.c: - Re-work main page (which was based on the misconception
>                        that this library always gets used)
>                      - Update group description

Applied, thanks Duncan.

Re: [PATCH libnfnetlink 0/1] Minimally resurrect doxygen documentation

[Duncan Roe]

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.