From: Michael Widenius Date: June 24 2009 2:53pm Subject: Re: MySql coding style: Request for change regarding documentation. List-Archive: http://lists.mysql.com/internals/36983 Message-Id: <19010.15840.137685.378798@narttu.askmonty.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Hi! >>>>> "Tor" == Tor Didriksen writes: Tor> On Mon, 22 Jun 2009 19:01:32 +0200, Dmitry Lenev wrote: >> Hello Tor! >> >> * Tor Didriksen [09/06/22 17:55]: >>> "function and method comments should be placed in front of >>> implementation rather than declaration" >>> >>> I find it quite strange that member functions should be documented in >>> the .cc file rather than the .h file, especially if these are public >>> member functions (part of the public interface of the class). >> >> AFAIR one of the reasons behind current rule is that ctags/etags tool >> which many of us use for navigating through the sources allows easily >> jump to function definition. So by keeping function description nearby >> its definition we are able to reach that comment from the place there >> it is used with one key-stroke. >> >> I am not sure if the same thing can be easily achieved if the comments >> will be placed nearby function declaration. >> Tor> I use tags as well, and it's fairly easy to jump to the next match. Tor> In emacs it's M-. for the firts, then M-0-. for the next and so on. Tor> Tags doesn't to any 'ranking', it just searches from the beginning Tor> of the TAGS file. It's fairly easy to write a wrapper which sorts Tor> .h files before .cc files. Tor> That will give you better tags for classes/structs. Tor> Another trick I've used in the past is to filter away forward declarations, Tor> to avoid matching them at all. The problem with the above is that when you code, you have to do much more jumping while you examine the related code in other functions. Regards, Monty