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