List:Internals« Previous MessageNext Message »
From:Davi Arnaut Date:April 13 2010 11:08am
Subject:Re: doxygen comments in header files
View as plain text  
On 4/13/10 1:53 AM, Michael Widenius wrote:
>
> Hi!
>
>>>>>> "Davi" == Davi Arnaut<Davi.Arnaut@stripped>  writes:
>
> Davi>  Hi Timour,
> Davi>  On 4/11/10 12:39 AM, Timour Katchaounov wrote:
>>> Guilhem, guys,
>>>
>>> I'd say, enough theoretical talk. Could each proponent
>>> of a specific method of commenting pick some class, and
>>> send to the list a sample with comments for both the
>>> interface and implementation of few class members.
>>> Such an example should contain a complete meaningful
>>> description, not just a formal description of parameters
>>> and results.
>
> Davi>  Besides Monty, I think everybody else is in agreement.
>
> Davi, please don't generalise when you don't have all the facts ;)

I'm not generalizing. Timour asked about "each proponent" and I simply 
pointed out that at that point of the discussion everybody (that 
participated, not the whole world) expect you was in agreement (ie they 
were consistent wrt method). I can quote if necessary.

> Not everyone that is coding on MySQL has given their opinion.
> You should assume that those that are silent are voting for keeping
> things as they are...

That's not how it works, otherwise you would be generalizing. Usually, 
silence is consent. Also, don't appear to claim something as "bad" if 
you are going to do it a few lines below :-)

>>> Having such examples would make it much clearer to everyone
>>> who means what, and will hopefully make it easier to conclude
>>> what are the pros and cons of each approach and come to a
>>> decision.
>
> Davi>  A C example:
>
> Davi>  tennis.h:
> Davi>  	/**
> Davi>  	Strike the ball with a backhand shot.
>
> Davi>  	@param direction  Direction of the stroke (where ball goes).
> Davi>  	@param hand  Whether the stroke is one-handed or two-handed.
> Davi>  	@param topspin  Forward rotation applied to the ball.
>
> Davi>  	@remark A two-handed backhand is more accurate and imparts
> Davi>  		topspin better. A one-handed backhand allows greater
> Davi>                     reach with much pace and penetration.
>
> Davi>  	@retval TRUE  You lose.
> Davi>  	@retval FALSE Ball has hit the court.
> Davi>  	*/
> Davi>  	bool throw_backhand(type direction, type hand, type topspin);
>
> Davi>  tennis.c:
>
> Davi>  	/**
> Davi>  	@details A backhand starts with the back of the hand facing
> Davi>  	in the direction of the stroke, typically starting with the
> Davi>  	arm crossing the body. They keys of a backhands are: footwork,
> Davi>  	shoulder turn, racket preparation and follow through.
>
> Davi>  	@return Whether the ball has landed within court limits.
> Davi>  	*/
> Davi>  	bool throw_backhand(type direction, type hand, type topspin)
> Davi>  	{
> Davi>  		type racket_data;
> Davi>  		prepare_foot();
> Davi>  		turn_shoulder();
> Davi>  		racket_data = prepare_racket(hand, topspin);
> Davi>  		return strike_ball(racket_data, direction);
> Davi>  	}
>
> What I am talking about is that I want to have all the remarks and
> parameter descriptions also in the .c file.  Just because you have
> documented things in the .h file, you shouldn't make the .c file
> harder to read.

It's not harder to use. Jumping to a header to read necessary stuff is 
not harder. Perhaps we have different definitions of what is "hard". 
"Hard" for me is something that requires a great deal of endurance in 
difficult, painful process. A few additional keystrokes is merely a 
minor annoyance.

> <cut>
>
> Davi>  I think there is really just one suggestion. In a nutshell, document
> Davi>  interface in headers, document implementation in source file.
>
> No, there is many suggestions, as this thread has shown.

Expect yours, they all seemed to be the same thing. Precisely, which one 
have I missed?

Regards,

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