> 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).
