Re: [PATCH] src: Enable doxygen to generate Function Documentation

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

(cc'ing list - already sent to Pablo)

Hi Pablo,

On Sat, Sep 14, 2019 at 01:25:56PM +1000, Duncan Roe wrote:
> Hi Pablo,
>
> On Sun, Sep 08, 2019 at 06:25:05PM +1000, Duncan Roe wrote:
> > The C source files all contain doxygen documentation for each defined function
> > but this was not appearing in the generated HTML.
> > Fix is to move all EXPORT_SYMBOL macro calls to after the function definition.
> > Doxygen seems to otherwise forget the documentation on encountering
> > EXPORT_SYMBOL which is flagged in the EXCLUDE_SYMBOLS tag in doxygen.cfg.in.
> > I encountered this "feature" in doxygen 1.8.9.1 but it still appears to be
> > present in 1.8.16
> >
> > Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
> > ---
> >  src/attr.c     | 70 +++++++++++++++++++++++++++++-----------------------------
> >  src/callback.c |  4 ++--
> >  src/nlmsg.c    | 40 ++++++++++++++++-----------------
> >  src/socket.c   | 22 +++++++++---------
> >  4 files changed, 68 insertions(+), 68 deletions(-)
> >
> > diff --git a/src/attr.c b/src/attr.c
> > index 0359ba9..ca42d3e 100644
> > --- a/src/attr.c
> > +++ b/src/attr.c
> > @@ -35,11 +35,11 @@
> >   *
> >   * This function returns the attribute type.
> >   */
> > -EXPORT_SYMBOL(mnl_attr_get_type);
> >  uint16_t mnl_attr_get_type(const struct nlattr *attr)
> >  {
> >  	return attr->nla_type & NLA_TYPE_MASK;
> >  }
> > +EXPORT_SYMBOL(mnl_attr_get_type);
> >
> [...]
>
> Oops! I forgot to say: this is a patch for libmnl.
>
> Cheers ... Duncan.

Any feedback re this patch?

Without it, libmnl documentation is seriously deficient.

Here for instance is the change to the generated man/man3/attr.3:

*** nopatch.3   2019-09-19 08:26:50.689755383 +1000
--- patch.3     2019-09-19 08:26:19.738592913 +1000
***************
*** 76,81 ****
--- 76,625 ----
          The payload of the Netlink message contains sequences of attributes
         that are expressed in TLV format.

+ Function Documentation
+    uint16_t mnl_attr_get_len (const struct nlattr * attr)
+        mnl_attr_get_len - get length of netlink attribute
+
+        Parameters:
+            attr pointer to netlink attribute
+
+        This function returns the attribute length that is the attribute header
+        plus the attribute payload.
+
+        Definition at line 51 of file attr.c.
+
+    void* mnl_attr_get_payload (const struct nlattr * attr)
[...]

(>500 lines of documentation added)

Cheers ... Duncan.