List:Internals« Previous MessageNext Message »
From:Davi Arnaut Date:April 11 2010 1:33pm
Subject:Re: doxygen comments in header files
View as plain text  
Hi Timour,

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.

Besides Monty, I think everybody else is in agreement.

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

A C example:

tennis.h:
	/**
	  Strike the ball with a backhand shot.

	  @param direction  Direction of the stroke (where ball goes).
	  @param hand  Whether the stroke is one-handed or two-handed.
	  @param topspin  Forward rotation applied to the ball.

	  @remark A two-handed backhand is more accurate and imparts
		  topspin better. A one-handed backhand allows greater
                   reach with much pace and penetration.

	  @retval TRUE  You lose.
	  @retval FALSE Ball has hit the court.
	*/
	bool throw_backhand(type direction, type hand, type topspin);

tennis.c:

	/**
	  @details A backhand starts with the back of the hand facing
	  in the direction of the stroke, typically starting with the
	  arm crossing the body. They keys of a backhands are: footwork,
	  shoulder turn, racket preparation and follow through.

	  @return Whether the ball has landed within court limits.
	*/
	bool throw_backhand(type direction, type hand, type topspin)
	{
		type racket_data;
		prepare_foot();
		turn_shoulder();
		racket_data = prepare_racket(hand, topspin);
		return strike_ball(racket_data, direction);
	}

> Also, it would be great if someone could summarize what are
> the suggestions, and what are the pros an cons. (Tor?) Otherwise
> this discussion can go on forever.

I think there is really just one suggestion. In a nutshell, document 
interface in headers, document implementation in source file.

Regards,

Davi



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