Re: [AD] Documentation update

[Hein Zelle <hein@xxxxxxxxxx>]

Eric Botcazou wrote:

> The problem is, Allegro is riddled with internal limitations on the size of
> buffers. I don't want to open a can of worms by accepting a first patch that
> hardcodes one of them. The patch is interesting only because it mentions the
> workaround. A more interesting one would be a patch that lifts the
> limitation.

Ah, I can see the problem then. I just get an itch between my
shoulders when I read "There is a limit on the length of such and such
string buffer" and I don't get to hear what the limit actually is. I
guess you're right about a solution with no buffer limit being best,
but that's probably not doable for the whole of allegro while keeping
the code clean and fast.

I'm still tempted to list absolute limits on parameters where they
exist, even if it is a can of worms.

> Internal limitations are not easy to document, because they are usually not
> directly translatable into limitations on the parameters of a API function.

Is that because unicode doesn't specify in advance how the length and
size of the string relate? If so, I'd just mention the limit in bytes
and have the programmer figure it out.

> As for the failure mode, it is simple: null-terminated truncation, we have a
> very effective API for that.

So it doesn't cause an error but your parameter string gets copied
only partially? In that case I guess the problem isn't very severe,
more a nuisance. I still stick to the opinion that the limit should be
documented though, I think. Which in no way means you have to agree,
as you're probably aware :-)

Hein Zelle

>-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-< 
 Unix is user friendly. It's just very particular about who 
 it's friends are.

 Hein Zelle                     hein@xxxxxxxxxx
	                        http://www.icce.rug.nl/~hein
>-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-<