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: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-04-22 08:11:16

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Edward Diener
> Sent: 21 April 2016 22:39
> To: boost_at_[hidden]
> Subject: Re: [boost] Ordering the header files in the library's doxygen reference
> 
> 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 !

Would it help diagnosing the problem to generate Standalone Doxygen and see if the order is what you want there?

Or could it work if you use a wild card to select all the files in one jamfile item like

[ glob ../../../boost/your_lib/*.hpp ]

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]