This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: style convention: /*foo_p=*/ to annotate bool arguments
* Jeff Law:
> On 10/04/2016 03:08 PM, Jason Merrill wrote:
>> In GCC sources, I think users look at the function definition more
>> often than the declaration in the header, the latter of which
>> typically has neither comments nor parameter names.
> So true. One could claim that our coding standards made a fundamental
> mistake -- by having all the API documentation at the implementation
> rather than at the declaration. Sigh....
The counterargument is that having the comment closer to the
implementation increases the likelihood that the comments are updated
along with code changes.
And with C++, certain programming styles favor emergent APIs, where
neither declaration nor definition are appropriate places for
documentation. One really old example are the << overloads for
iostreams, particularly when it comes to manipulators.
In the end, I suspect this can only be addressed in a satisfactory
manner by good code browsing tools (preferably with editor and patch
review integration).