>>>>> "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
Davi> A C example:
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> bool throw_backhand(type direction, type hand, type topspin);
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> bool throw_backhand(type direction, type hand, type topspin)
Davi> type racket_data;
Davi> racket_data = prepare_racket(hand, topspin);
Davi> return strike_ball(racket_data, direction);
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.
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.