List:Internals« Previous MessageNext Message »
From:Dmitry Lenev Date:June 23 2009 9:42am
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
Hello Tor!

* Tor Didriksen <Tor.Didriksen@stripped> [09/06/23 12:59]:
> On Mon, 22 Jun 2009 19:01:32 +0200, Dmitry Lenev <dlenev@stripped> wrote:
>
>> * Tor Didriksen <Tor.Didriksen@stripped> [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.
>>
>
> I use tags as well, and it's fairly easy to jump to the next match.
> In emacs it's M-. for the firts, then M-0-. for the next and so on.

Indeed. Other editors support this as well.

>
> Tags doesn't to any 'ranking', it just searches from the beginning
> of the TAGS file. It's fairly easy to write a wrapper which sorts
> .h files before .cc files.

Well... Have you tried doing "make ctags" and searching for matches
say for for mysql_alter_table() ? In my case it gives only one match
which corresponds to definition of this function. So there is no way
to jump to function declaration in the header file...

Note that I am not saying that it is impossible to achieve behavior
which you have described, I'm just pointing out that if you proposal
will be accepted we will have to adjust something in the way we
produce tag files. And it is better to figure out what exactly should
be done before the proposal is accepted.

-- 
Dmitry Lenev, Software Developer
MySQL AB, www.mysql.com

Are you MySQL certified?  http://www.mysql.com/certification
Thread
MySql coding style: Request for change regarding documentation.Tor Didriksen22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Jay Pipes22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun
      • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN24 Jun
        • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Joerg Bruehe25 Jun
  • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov22 Jun
    • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
    • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
  • Re: MySql coding style: Request for change regarding documentation.Guilhem Bichot22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev23 Jun
        • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun