Re: Tool maintenance

From: Edward Diener (eldiener_at_[hidden])
Date: 2021-05-26 23:02:07

On 5/26/2021 3:41 PM, Andrey Semashev via Boost wrote:
> 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 

Thank you very much, Andrey. I am not intending to criticize Daniel 
James but evidently his idea of documentation for BoostBook on the level 
of xsl parameters was "read the source". I am, however, really happy 
that you figured it out.