| Re: [AD] Docs and set_gfx_mode |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On 2004-09-24, Christer Sandberg <christer.sandberg@xxxxxxxxxx> wrote:
> documentation was written by programmers for programmers. This
> means,
>
> I hope you meant "for Allegro programmers"
Well, that would discard me then. Hmmmm... I wrote my last program
using Allegro more than five years ago. Why the heck I'm still
on these mailing lists I'll never know. Oh, yeah, documentation
patches... hmmm...
> How to document a function? - [...] Is there an agreement about
> some "layout convention" of the type sketched above, for future
> docs?
No, there isn't. The problem is that if you make a strict rule
of always trying to follow a style, you will find that there are
many different types of "things" to document in Allegro which just
don't fit with the style. And there's the problem with the Allegro
manual being both a read-from-top-to-bottom document as in .txt,
rtf, pdf format or jump-to-reference like info. In the former you
are reading everything in a row, so it makes sense to put those
"see below for more information". In info like format, you see the
single function you are reading, and there's no below, up or down
in a practical sense. It is even more drastic in unix manpages,
which are physically cut off from other bits.
It's a mess. But nobody will care, I'm positive your suggestion
will be better than what there is at the moment, so use the style
you prefer. The Allegro hacking guide has some suggestions about
what the documentation should state. Again, just suggestions.
> > 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).
Buy that poor English some self-esteem. Mine is worse.