From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2021-05-26 19:41:31
On 5/26/21 10:22 PM, Andrey Semashev wrote:
> On 5/26/21 8:30 PM, Edward Diener via Boost wrote:
>> On 5/26/2021 1:03 PM, Andrey Semashev via Boost wrote:
>>> On 5/26/21 7:46 PM, Edward Diener via Boost wrote:
>>>> On 5/25/2021 2:00 PM, Glen Fernandes via Boost wrote:
>>>>> On Tue, May 25, 2021 at 12:22 PM Edward Diener wrote:
>>>>>> I have discovered a serious bug with BoostBook and nested namespaces,
>>>>>> created an issue, but fear that no one will respond. I would like to
>>>>>> e-mail anybody who is a maintainer for BoostBook who might be able to
>>>>>> look at the issue and fix it, but there is no list of maintainers for
>>>>>> Boost tools which I can find. The person who appears to have
>>>>>> worked with
>>>>>> BoostBook in the past, Daniel James, is no longer active with
>>>>>> Boost so I
>>>>>> have no idea who might be able to fix the issue.
>>>>> BoostBook has no active maintainer right now.
>>>> Too bad, as the bug will not be fixed. Am I really the only person
>>>> using the quickbook/boostbook/doxygen toolchains to document a
>>>> library with doxygen documentation for entities in a nested
>>>> namespace ? It seems so. I guess I will have to except the fact that
>>>> the nested namespace entities will never be documented in the
>>>> doxygen-generated reference for a library.
>>> We have libraries that use QuickBook+Doxygen (I'm a maintainer of at
>>> least two), so you're definitely not alone. At least, in Boost.Log I
>>> have multiple nested namespaces, and I don't remember having a
>>> problem of symbols not documented in the nested namespaces. That
>>> said, I haven't built the docs locally for some time, so maybe
>>> something got broken...
>> Could you try building your docs locally with the latest 'develop'
>> branch ?
> I get errors "Error: no ID for constraint linkend" that I remember
> having before (https://github.com/boostorg/quickbook/issues/11), but
> other than that the build succeeds. The generated reference section
> contains expected symbols (the few I checked, anyway).
>> Can you try the example at
>> https://github.com/boostorg/boostbook/issues/10 and see if you are
>> also seeing what I am seeing ?
> Yes, the example::detail::example_value class template is not present in
> the final docs. However, if I rename the namespace to e.g. detail_ns
> then example_value is present in the output.
> I think, this has something to do with the boost.doxygen.detailns
> parameter, which is "detail" by default and is supposed to denote the
> namespace with implementation details that have to be omitted from the
> docs. However, setting it to a different value in the Jamfile didn't
> work for me, so ether it's something different or the user-specified
> value does not apply for some reason.
Ah, I added the parameter at the wrong place initially, so it didn't work.
If you add "<xsl:param>boost.doxygen.detailns=aux" to the "doxygen
example_reference" rule requirements, along with other <doxygen:param>
tags, the example_value appears in the output. Here, "aux" is the detail
namespace name you want to hide.
BTW, the parameter is defined here:
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk