List:Internals« Previous MessageNext Message »
From:Michael Widenius Date:April 13 2010 4:53am
Subject:Re: doxygen comments in header files
View as plain text  
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 ;)
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...

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

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

Regards,
Monty
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