09/10/2025 19:55, Morten Brørup:
> > From: Thomas Monjalon [mailto:[email protected]]
> > Sent: Thursday, 9 October 2025 19.29
> >
> > 09/10/2025 19:12, Morten Brørup:
> > > From: Bruce Richardson [mailto:[email protected]]
> > > > 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.
