[PATCH v8 1/3] mbuf: de-inline sanity checking a reinitialized mbuf

[Thomas Monjalon]

09/10/2025 19:55, Morten Brørup:
> > From: Thomas Monjalon [mailto:thomas at monjalon.net]
> > Sent: Thursday, 9 October 2025 19.29
> > 
> > 09/10/2025 19:12, Morten Brørup:
> > > From: Bruce Richardson [mailto:bruce.richardson at intel.com]
> > > > On Sat, Aug 23, 2025 at 06:30:00AM +0000, Morten Brørup wrote:
> > > > > +/**  check reinitialized mbuf type in debug mode */
> > > >
> > > > This is in release mode, not debug mode. Comment below seems wrong
> > too.
> > >
> > > Yes, I noticed the comment was present in both debug and release
> > mode,
> > > which I couldn't understand. So I guessed it was for Doxygen or some
> > other parser.
> > > I have seen weird stuff for Doxygen, e.g. "#ifdef __DOXYGEN__"
> > > for documenting a function [1],
> > > so I didn't attempt to understand the reason for it,
> > > but just followed the same pattern.
> > 
> > Hum, as a maintainer, I would prefer you try to understand, or ask
> > please.
> > Note: we can use Slack for such questions.
> 
> Point taken. Good guidance!
> I'll try to broaden my scope of knowledge to include preprocessing for Doxygen.
> 
> > __DOXYGEN__ is defined only by Doxygen,
> > so any code inside #ifdef __DOXYGEN__ is for documentation only.
> > It was supposed to be used in lib/eal/include/generic
> > for functions which are really defined inline per CPU implementation.
> 
> Yes, I get that.
> But I don't get - when there are two definitions of a macro -
> why is the same comment/documentation present in both instances?

Because the author had no better idea I suppose.


> And if the instances have different comments/documentation,
> how is that reflected in the documentation output from Doxygen?

You can have only one instance of a symbol in Doxygen.


> In this specific case, how should the code look to both
> 1) get the wanted Doxygen documentation output,

#if defined RTE_LIBRTE_MBUF_DEBUG || defined __DOXYGEN__

/** Check reinitialized mbuf type in debug mode. */
#define __rte_mbuf_raw_sanity_check_mp(m, mp) rte_mbuf_raw_sanity_check(m, mp)
/** Check mbuf type in debug mode. */
#define __rte_mbuf_sanity_check(m, is_h) rte_mbuf_sanity_check(m, is_h)

#else /* !RTE_LIBRTE_MBUF_DEBUG */

#define __rte_mbuf_raw_sanity_check_mp(m, mp) do { } while (0)
#define __rte_mbuf_sanity_check(m, is_h) do { } while (0)

#endif /* RTE_LIBRTE_MBUF_DEBUG */


> and 2) have relevant comments inline in the source code for both instances?

No need to comment in release mode, it is not relevant for debug macros.