Re: [lmi] [lmi-commits] master 783f4dd 5/9: Consolidate and revise documentation

[Vadim Zeitlin]

On Wed,  4 Apr 2018 21:27:37 -0400 (EDT) Greg Chicares <address@hidden> wrote:

GC> branch: master
GC> commit 783f4dd835466ada15c6ff38c934ae605639f26a
GC> Author: Gregory W. Chicares <address@hidden>
GC> Commit: Gregory W. Chicares <address@hidden>
GC> 
GC>     Consolidate and revise documentation
GC>     
GC>     It seems generally best to comment a member function in one place only:
GC>     at its point of definition.

 Would it be possible to discuss the rationale for this rule? Personally, I
find it very inconvenient to have comments explaining what the function
does (as opposed to how it does it) near its definition, as opposed to its
declaration, which is where I'm looking if I have any questions about the
function (e.g. by jumping to a tag in Vim). Of course, the fact that it's
very unusual doesn't mean that it's necessary wrong, but it's still worth
mentioning that lmi is the only project I know of which doesn't put
comments near the function declaration and so I'm quite sure that I'm not
the only one who is confused by not finding them in the header.

 Finally, there is a question of consistency: documentation comment of a
class is, necessarily, located before its declaration, as there is no
definition for it. Why should it be different for the functions?

 I really wish this rule could be changed and the documentation comments
could appear at the point of function declaration instead. It would
definitely make reading them much more convenient for me personally and I
just don't see any drawback of keeping them there.

 What am I missing? Why does lmi do it differently from all the other C++
(and even C) headers in existence?

VZ