* Joel Sherrill:
>> This approach is far less useful for languages which haven't got
>> separate spec files because it encourages programmers of client code
>> to look at the implementation, potentially picking up implementation
>> details. It encourages the documentation writer to accidentally refer
>> to internals, too.
> That's a matter of style and project code style enforcement.
To my knowledge, the GNU project has no guidelines for the contents of
C header files, and heavy use of the preprocessor is rather common. 8-(
>> I don't think it works at all for modern C++ code where the surface
>> syntax of an API is an emerging property. (The API of foo's type
>> ensures that "if (foo) { ...}" works as expected, but the exact
>> language mechanism which achieves that is an implementation detail, so
>> you can't really attach a docstring to it.)
>>
>>
> So....? As a user, I don't care how you implemented it.
That's precisely my point. Doxygen-style documentation would have to
be attached to an implementation detail, something that the user does
not actually care about.
