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

[Duncan Roe <duncan_roe@optusnet.com.au>]

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.