List:Internals« Previous MessageNext Message »
From:Tor Didriksen Date:June 23 2009 10:10am
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
On Tue, 23 Jun 2009 11:42:32 +0200, Dmitry Lenev <dlenev@stripped> wrote:

> 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...
>
That's just an extra flag to etags.

=== modified file 'support-files/build-tags'
--- support-files/build-tags	2008-12-24 10:48:24 +0000
+++ support-files/build-tags	2009-06-23 10:07:18 +0000
@@ -8,5 +8,5 @@

  $list |grep $filter |while read f;
  do
-	 etags -o TAGS --append $f
+	 etags --declarations -o TAGS --append $f

-- didrik

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


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