Re: [lmi] Does doxygen's client-side search work?

[Greg Chicares]

On 4/26/23 13:56, Vadim Zeitlin wrote:
> On Wed, 26 Apr 2023 03:07:22 +0000 Greg Chicares <gchicares@sbcglobal.net> 
> wrote:
> 
> GC> The lmi search box here:
> GC>   https://www.nongnu.org/lmi/doxygen/
> GC> doesn't work for me,
> 
>  It doesn't work because it relies on having JavaScript (and also CSS)
> files on the server which are not found there.

Thanks, I've uploaded the contents of the entire search/ subdirectory,
and now searching seems to work.

> GC> Perhaps it would be better for lmi to set:
> GC>   SEARCHENGINE           = NO
> GC> because tools like git-grep and vim are probably
> GC> better than doxygen's search.
> 
>  You'd think so, but from my personal experience, not being able to search
> the docs was a very big problem for wx users, so I'd recommend fixing it if
> it can be done easily.

Me, I don't think I ever even noticed that doxygen had a search
facility: if I wanted to look up "wxMenuBar", I already knew its name.

But the fix was easy, and for lmi the doxygen search does present
a better appearance: that is, it makes the documentation more
"accessible", and at no cost. For example, to learn about premium
taxes, a search for "tax" leads easily enough to class premium_tax,
whose "Detailed Description" is pretty good, though of course it
won't make much sense to anyone who knows nothing about US state
premium taxes.

A comprehensive understanding of lmi's premium-tax implementation
is still most easily gotten by reading the source code. For example,
free function premium_tax_is_retaliatory() is documented here:

https://www.nongnu.org/lmi/doxygen/namespaceanonymous__namespace_02premium__tax_8cpp_03.html#a86bc15cf098e8bc8049f457da76ed861

but that's not linked to the documentation for class premium_tax,
AFAICS. Free functions improve encapsulation, but make automatic
documentation extraction harder. The doxygen pages can help one
gain a high-level, top-down understanding and suggest where to
look for deeper detail; but deep understanding is best gained
by the old-school, bottom-up method of reading the source.