Re: Tool maintenance

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2021-05-26 19:22:55

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.