Re: [Boost-docs] Doxygen (non)-processing of namespace detail

Subject: Re: [Boost-docs] Doxygen (non)-processing of namespace detail
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-03-11 10:57:26

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Daniel James
> Sent: 10 March 2016 19:56
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] Doxygen (non)-processing of namespace detail
> 
> On 9 March 2016 at 17:17, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> >
> >   <!-- The namespace used to identify code that should not be  processed at all. -->
> >   <xsl:param name="boost.doxygen.detailns">detail</xsl:param>
> >
> >   <!-- The substring used to identify unspecified types that we can't
> >        mask from within Doxygen. This is a hack (big surprise). -->
> >   <xsl:param name="boost.doxygen.detail"><xsl:value-of select="$boost.doxygen.detailns"/>::</xsl:param>
> 
> As these are parameters, you can specify the value in your jamfile. So
> if you don't want it, set boost.doxygen.detailns to a string that will
> never match, e.g.

    <xsl:param>boost.doxygen.detailns=dont-ignore-detail-namespace

I can confirm that this does as you suggest and allows use of the more flexible (but more work)
doxygen \cond  A_MACRO ... \endmacro mechanism to select what and when should be processed through into the final html.
 
> > My experiments seem to show that namespace 'details' is also not processes (but detai is).
> 
> Looking at the xsl it uses 'contains' to check for detail namespaces,
> so it's going to match anything including 'detail'. It could be
> changed to something like: contains(concat('::',$fullname,'::'),
> concat('::',$boost.doxygen.detailns,'::')). Although I wouldn't be
> surprised if some documentation relies on the existing behaviour.
> 
> > Since one might want Doxygen to process details for maintenance, this seems a rather blunt mechanism, compared to
> >
> > 1 Not processing header files with Doxygen that contain detail sections by choice of input in doxyfile/ jamfile.
> 
> Can't do that in XSL, you'd have to work out how to do it in boost
> build. It might just be a case of using globs to select the right
> files.
> 
> > 2 Using the Doxygen mechanism \cond BOOST_DETAIL ... \endcond to control what is 'Doxygenated' into the boostbook.
> 
> Maybe.

This works nicely for me, allowing the implementation details to be documented, but only 'revealed' 'on demand' for anyone doing
maintenance.

Thanks again.

Paul