Re: [AD] Docs and set_gfx_mode

[Elias Pschernig <allefant@xxxxxxxxxx>]

On Fri, 2004-09-24 at 15:54 +0200, Christer Sandberg wrote:

> How to document a function? - One possible general form is to first
> describe what a function does in general followed by a list of all
> parameters, each explained in detail (including exceptions of the
> general behavior of the function) and finally an explanation of the
> return value. I'm quite comfortable with that form myself, and use to
> encourage others to use it as well. 
> 

I agree, that's how functions should be documented. And I think most
function follow that already in the allegro docs. And as Grzegorz said,
we need help by people finding the ones which don't and send us better
versions :)

> In case there are lots of details to be said about a function or its
> parameters, then the description can be done in two levels, specially if
> there is a simple "normal" usage, assumed to be used more often by a
> beginner. What I mean is something like "Simple usage:" followed by an
> explanation of the simple usage, thereafter an exhaustive explanation
> (similar to e.g. the man page about cvs).
> 
> Is there an agreement about some "layout convention" of the type
> sketched above, for future docs?
> 

Well, what we have is the ._tx format. The Allegro API docs are created
from docs/src/allegro._tx. Look there for set_gfx_mode. It should be
easy to figure the format out, and you can also look at
docs/src/makedoc/format.txt (which will scare you, so better just look
at the ._tx and how functions are documented there).

-- 
Elias Pschernig