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


This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC