RE: _bit_scan_forward

["Young, Michael" <Michael dot Young at paetec dot com>]

> This is a reason that I personally don't like doxygen documentation.
> It isn't clearly separated into interface functions and internal
> functions.

Do you know of a better tool?  If so, I'm interested, because I have
"issues" with Doxygen, too - IMHO, it does have some "warts".  However...

AFAICT, the problem really isn't with Doxygen.  How does C or C++ really 
specify that a function is an "interface" vs. "internal"?  They don't...
one could argue that the C++ access specifiers on member functions are
the same thing, but, it reality, they're not quite.  (In most cases they're
synonymous, but what members are/are not intended for use by a "friend"?  
That's why there's the Client/Attorney "pattern"...)  [On a related note :
access specifiers aren't there for encapsulation, either - that's why there's
a "pimpl" (handle/body) idiom.]  In C, there's really truly nothing for this...

Anyway, the languages lack a formal way to specify interface vs. internal 
implementation.  Note that even if there's a way to do this, then the 
question becomes, "Which interface is appropriate to use for which 
application / code layer?"  So the real answer is that the developer should
explicitly "identify" the function as internal/interface, along with the 
interface name/category, (easily done using preprocessor definitions and
conditionals) when the documentation is created.  (There may be other ways
to deal with this, too - probably best to ask the Doxygen team for ideas.)
Of course, even if you manage to identify the files/sections/functions
appropriate for each audience, you must then typically generate "multiple 
sets" of docs - one for internal developers and one for 3rd parties, for 
example.  [Side note : I've often wondered if I could generate a single
doc set that can present only the views "accessible" by an identified
user, but I've never really invetigated/pursued this...]  Alternatively,
you can choose to not create "pretty" docs for the internal stuff - but 
if you have to learn the tool / tags to create the interface docs anyway,
the tool is easy to use, and the doc is useful for the next maintainer 
(you know - that homicidal maniac who knows where you live, or, in my case,
that ADHD developer who can't remember anything and lives where I live),
why not???  Finally, there's the "brute force" approach that just creates a
description line that explicitly states into which "camp" the function falls;
this leaves the "enforcement" up to the client developer and hides nothing,
but it is generally the simplest approach to implement, too.

I understand that it's difficult to "reverse engineer" and document functions
properly "after the fact" (i.e., usually much later than the code creation,
and often after the original developer is no longer available for consultation).
There isn't a perfect solution for that situation, at least not until Vulcan 
mind-melds and collective cognition come along!  But I think Doxygen provides
a reasonable approach - it allows you to document "what is" relatively quickly,
and that hopefully makes the code base easier to "grok".

This is a little off-topic, but gripes about tools that are not being fully
utilized or understood is something the GCC community has a vested interest
in dispelling!  In all fairness, the issue here may be with how GCC developers
are documenting code, rather than a real problem with the tool!  ;-)

  - Mike

BTW - I am not a Doxygen contributor, and I have not ever used it at a paid
job, but I do use it for my own "projects" (currently, my masters thesis 
project).