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