Re: [AD] Docs and set_gfx_mode

[Christer Sandberg <christer.sandberg@xxxxxxxxxx>]

On Fri, 2004-09-24 at 10:19, Grzegorz Adam Hankiewicz wrote:
documentation was written by programmers for programmers. This means,

I hope you meant "for Allegro programmers", that's what I sometimes
experience as the problem: sometimes you need to already know quite a
lot about Allegro to be able to fully understand a certain doc item.

I think it's good if the docs of a lib is not too abundant, and it
should be a user requirement (that is, 'lib user') to have at least a
little knowledge about programming. The problem is sometimes rather that
the docs is not directed to programmers.

E.g. in the case of 'set_gfx_mode' the docs says "..if you don't care
about virtual screen pass 0..", but as a programmer I want to know the
exact semantics of the various possibilities of any input parameter. 

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. 

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?

> The best thing you could do is rewrite the description
> of set_gfx_mode just as you like it best without regards for

Well, I can make a try at least (I need to figure out some semantics,
and there is also a problem that my English is a bit poor).

-- 
Christer Sandberg <csg01@xxxxxxxxxx>