More bad documentation

SDL Development
1

The inline comments in SDL_video.h give the wrong function
prototypes for SDL_SetRenderDrawColor and
SDL_GetRenderDrawColor. (And before anyone says UTSL
again, I’m trying to translate the headers into Object Pascal.
Attention to detail is very important if my work ends up being
used by other people who don’t have any SL to U.)

2

And before anyone says UTSL again

Actually, this is useful information, as these comments tend to rot as
we’re still building and adjusting the 1.3 API (and hopefully they will
be useful for Doxygen at some point, too), so I’m glad someone is
checking them for accuracy.

–ryan.

3

The inline comments in SDL_video.h give the wrong function
prototypes for SDL_SetRenderDrawColor and
SDL_GetRenderDrawColor.? (And before anyone says UTSL
again, I’m trying to translate the headers into Object Pascal.
Attention to detail is very important if my work ends up being
used by other people who don’t have any SL to U.)

You keep sending them, I’ll try to keep fixing them.

BTW, I see what is wrong with SDL_GetRenderDrawColor, but I don’t see
the error in SetRenderDrawColor?

Bob PendletonOn Wed, Jul 1, 2009 at 10:43 PM, Mason Wheeler wrote:

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

–
±----------------------------------------------------------

4

BTW, I see what is wrong with SDL_GetRenderDrawColor, but I don’t see
the error in SetRenderDrawColor?

Wrong return type.>From: Bob Pendleton

Subject: Re: [SDL] More bad documentation

5

BTW, I see what is wrong with SDL_GetRenderDrawColor, but I don’t see
the error in SetRenderDrawColor?

Wrong return type.

OK, all fixed.

Bob PendletonOn Thu, Jul 2, 2009 at 11:46 AM, Mason Wheeler wrote:

From: Bob Pendleton <@Bob_Pendleton>
Subject: Re: [SDL] More bad documentation

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

–
±----------------------------------------------------------

6

Ryan C. Gordon wrote:

And before anyone says UTSL again

Actually, this is useful information, as these comments tend to rot as
we’re still building and adjusting the 1.3 API (and hopefully they
will be useful for Doxygen at some point, too), so I’m glad someone is
checking them for accuracy.
I began to wonder why the \fn keyword requires the prototype to be
repeated and ended up stumbling on this amusingly (the last sentence)
enough:

Because each comment block in the example above contains a structural
command, all the comment blocks could be moved to another location or
input file (the source file for instance), without affecting the
generated documentation. The disadvantage of this approach is that
prototypes are duplicated, so all changes have to be made twice! Because
of this you should first consider if this is really needed, and avoid
structural commands if possible. I often receive examples that contain
\fn command in comment blocks which are place in front of a function.
This is clearly a case where the \fn command is redundant and will only
lead to problems.

from: http://www.stack.nl/~dimitri/doxygen/docblocks.html

Usually doxygen is able to just pick the prototype from the C or C++
code directly after the docblock, the \fn keyword is for the case where
you want the docblock not in the same location as the function itself.

I can comprehend a reason why it might be necessary: preventing seeing
storage class and the declspec token in the output. But there is a
solution to that: http://www.stack.nl/~dimitri/doxygen/preprocessing.html

Maybe there is another reason, but I decided to post regardless because
of that paragraph in the documentation I thought was interesting.

–jkl