Re: [lmi] Doxygen: BUILTIN_STL_SUPPORT

[Vadim Zeitlin]

On Wed, 12 Apr 2023 22:32:55 +0000 Greg Chicares <gchicares@sbcglobal.net> 
wrote:

GC> With doxygen-1.9.4, there's an option that isn't mentioned
GC> in wx's 'docs/doxygen/Doxyfile' of doxygen-1.8.8 vintage:
GC> 
GC>   # If you use STL classes (i.e. std::string, std::vector, etc.) but do not 
want
GC>   # to include (a tag file for) the STL sources as input, then you should 
set this
GC>   # tag to YES in order to let doxygen match functions declarations and
GC>   # definitions whose arguments contain STL classes (e.g. func(std::string);
GC>   # versus func(std::string) {}). This also make the inheritance and 
collaboration
GC>   # diagrams that involve STL classes more complete and accurate.
GC>   # The default value is: NO.
GC> 
GC>   BUILTIN_STL_SUPPORT    = YES

 Thanks for the pointer but, just to be clear: this option is present in
the wx Doxyfile (because it's not new at all and I'm almost sure, even if
I'm too lazy to check, that it existed in Doxygen versions much older than
1.8.8), but it has its default value of "NO".

GC> Perhaps it might be beneficial for wx to use it when STL
GC> becomes the default; or maybe it's too noisy.

 Maybe I'm doing something wrong, but it doesn't seem to make any
difference to me. In a few places where wx documentation refers to
std::string, nothing changes when I enable it. I thought std::string would
be hyperlinked (although I'm not entirely sure to what), but it isn't.

 FWIW we already link to http://en.cppreference.com/ manually in a couple
of places (see e.g. https://docs.wxwidgets.org/3.2/classwx_string.html).

GC> The effect of toggling it to "YES" is evident in the "collaboration
GC> diagram for lmi class yare_input:
GC> 
GC>  - with "NO", only members of type calendar_date are shown;
GC> 
GC>  - with "Yes", members of type string and of particular
GC>    vector<whatever> types are also shown.

 wxWidgets docs don't use collaboration diagrams at all, just the
inheritance ones, so if this is its only effect, it's probably not needed
there...

 Anyhow, even with the switch to wxUSE_STL==1 by default definitions of wx
container classes are going to remain too impenetrable for a simple
computer program such as Doxygen (and for common mortals) for a long time
yet because we have to keep a lot of compatibility baggage. In the new docs
(the PR still hasn't been merged yet, so I can't link to them), I just say
that all container classes should be treated as if they were std::vector<>,
or std::list<> etc, which should hopefully be good enough.

 Regards,
VZ

pgpsPSTwMGjB1.pgp
Description: PGP signature