Re: Tool maintenance

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:

https://github.com/boostorg/boostbook/blob/aa3d1d676ce2d921dc820bbea9ed38a39a279402/xsl/doxygen/doxygen2boostbook.xsl#L31