Re: [boost] Ordering the header files in the library's doxygen reference

Subject: Re: [boost] Ordering the header files in the library's doxygen reference
From: Edward Diener (eldiener_at_[hidden])
Date: 2016-04-21 17:38:52

On 4/21/2016 3:35 PM, Andrey Semashev wrote:
> On 2016-04-21 21:17, Edward Diener wrote:
>>
>> It's the order of the header files which shows in the reference section
>> to the VMD library documentation which concerns me. The order is garbled
>> from what I specify in my jamfile, which makes it much harder for an
>> end-user to look in the reference section to find a VMD macro. This is
>> occuring despite the fact that I specify the order which I want the
>> header files to be listed in the reference section of the jamfile.
>
> The Docbook XML document is generated by Doxygen and, I assume, the
> order in which the headers are listed in the document is determined by
> Doxygen and not the Jamfile.

I would assume so also. But I would also assume for the Boost.Build 
doxygen rule that the order of the 'sources' matches the order of INPUT 
files in the doxygen configuration file, else how else is the doxygen 
output being generated without an internal doxygen configuration. I also 
can see in the output from quickbook that doxygen is parsing the files 
in the exact order I give of the 'sources' to the doxygen rule. But I 
can also see in the output from quickbook that doxygen is generating 
docs for the files in the order that shows up in the final documentation 
and that the order of generating files is very different from the order 
it is parsing the files. You can see all this if you just look at the 
VMD library's doc jamfile and try generating the doc for it yourself.

I asked both on the doxygen user's mailing list and on stackoverflow why 
the order specified for the INPUT files does not match the order of 
files for which the docs are generated and which appear in the reference 
section, but there has been no answer to this. My guess is that the 
doxygen programmer knows why, or perhaps it is a bug in some  situation 
I am encountering, but he is not telling if he knows. I notice quite a 
few questions on the doxygen users mailing list never get answered.

>
> In Boost.Log docs I have the ALPHABETICAL_INDEX=YES Doxygen parameter,
> and in the generated docs the headers are listed alphabetically (within
> each Reference sub-section). Maybe that's what you're missing?

I tried it but it made no difference in the order of the generated 
files. I did not think it would work, according to the documentation for 
ALPHABETICAL_INDEX in the dosygen documentation file, and it did not. 
Thanks anyway !