List:Internals« Previous MessageNext Message »
From:Vladislav Vaintroub Date:April 15 2010 11:04pm
Subject:RE: doxygen comments in header files
View as plain text  

> -----Original Message-----
> From: Ingo.Struewing@stripped [mailto:Ingo.Struewing@stripped]
> Sent: Thursday, April 15, 2010 7:53 PM
> To: Guilhem Bichot
> Cc: internals
> Subject: Re: doxygen comments in header files
> 
> Hi Guilhem,
> 
> Guilhem Bichot, 15.04.2010 18:37:
> 
> > Hello Ingo,
> >
> > Ingo Strüwing a écrit, Le 12.04.2010 14:47:
> >> Hi Guilhem,
> >>
> >> Guilhem Bichot, 31.03.2010 11:53:
> >>
> >> ...
> >>>     I would like the rule to be changed at least for class
> >>> methods: I would like their comment to be in front of the
> declaration
> >>> (so inside the class declaration). In short and approximatively: in
> the
> >>> ".h" file, not in the ".cc" file.
> >>
> >> After all the pros and cons, I wonder, if a compromise could be
> >> thinkable: Have the interface specification at both places and have
> a
> >> tool that verifies the consistency at commit/push and/or build time?
> >
> > In theory this is very appealing. It makes happy the ones who want to
> > see all doc in the .cc (one single place to jump to), and the ones
> who
> > want to see the API in the .h.
> > In practice, I don't know how feasible it is.
> ...
> 
> 
> Sure, if nothing like this exists today, it could become a challenging
> task. What exactly should be checked is something to be defined.
> Another
> compromise (between features and implementation effort) might be
> required.
> 
> But before specifying this in detail, I'd like to hear voices, if this
> could become an acceptable compromise at all. After all, I could
> imagine
> that a remarkable amount of purists would reject it anyway.

I vote for specifying interface in header file and commenting on
implementation details in source file.  

It is not puristic point of view, just my IDE allows me to quickly jump to
either to definition or declaration, so I do not find it hard to look at 2
places. 
I like clean separation. If I know I'm looking for "what" function does, I
jump to declaration. If I need to know gory implementation details ("how"
function does it), I jump to definition.
 
> Regards
> Ingo
> --
> Ingo Strüwing, Database Group
> Sun Microsystems GmbH, Sonnenallee 1, D-85551 Kirchheim-Heimstetten
> Geschäftsführer: Jürgen Kunz                     HRB München
> 161028
> 
> --
> MySQL Internals Mailing List
> For list archives: http://lists.mysql.com/internals
> To unsubscribe:
> http://lists.mysql.com/internals?unsub=1


Thread
doxygen comments in header filesGuilhem Bichot31 Mar
  • Re: doxygen comments in header filesTor Didriksen6 Apr
    • Re: doxygen comments in header filesGuilhem Bichot6 Apr
      • Re: doxygen comments in header filesMats Kindahl6 Apr
    • Re: doxygen comments in header filesKristian Nielsen6 Apr
      • Re: doxygen comments in header filesGuilhem Bichot9 Apr
        • Re: doxygen comments in header filesTimour Katchaounov11 Apr
          • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesSergei Golubchik11 Apr
              • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                    • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesSergei Golubchik12 Apr
            • Re: doxygen comments in header filesMichael Widenius13 Apr
              • Re: doxygen comments in header filesDavi Arnaut13 Apr
    • Re: doxygen comments in header filesMichael Widenius6 Apr
      • Re: doxygen comments in header filesMARK CALLAGHAN6 Apr
        • Re: doxygen comments in header filesMichael Widenius13 Apr
  • Re: doxygen comments in header filesDavi Arnaut7 Apr
    • Re: doxygen comments in header filesGuilhem Bichot7 Apr
    • Re: doxygen comments in header filesKonstantin Osipov9 Apr
  • Re: doxygen comments in header filesIngo Strüwing12 Apr
    • Re: doxygen comments in header filesGuilhem Bichot15 Apr
      • Re: doxygen comments in header filesIngo Strüwing15 Apr
        • RE: doxygen comments in header filesVladislav Vaintroub16 Apr