RE: Overlay Documentation

["Pierangelo Masarati" <ando@sys-net.it>]

>> >useful extensions could easily make into the distributed source as
>> contribs, so I think it might be worth the effort to
>> document this part of
>> >the API as soon as it stabilizes.
>>
>> For SLAPI, I think we should just reference Netscape/Sun
>> documentation.
>> SLAPI is a compatibility interface after all.  I think we
>> should focus on
>> the maturity of native interfaces (e.g., ensuring the native
>> interfaces are
>> encompassing of our needs and well documented).
>
> I agree. I think we're still figuring out whether or not the native
> interfaces are suficient...

well, I need to admit that it was a bit hard to learn how to use overlays,
and I'm not sure yet what they do in some cases.  I'd like to find
documented "obvious" things like: I note that over_op_func() saves a copy
of the op->o_bd, rather than its pointer, before calling the overlays; is
it because you're afraid that someone along the path may alter the data,
so you just don't trust overlays, or there's a reason I'm missing?  In my
overlays I usually save a pointer to data I beed to replace and restore.
Again: I noted that in some cases, in back-relay, I need to explicitly
restore the callbacks removing the one I added; why? ... In this sense a
schematical documentation would help in finding out what the code does.  I
know the code is the source, but when it gets too involved (and callbacks
and nested structure casting are a bit too involved for me) it gets really
hard to tell what it does. I admit I'm learning a lot from your examples,
and I really appreciate it, but sometimes I find it easier to learn form
docs rather than from examples :)
>
>> >Of course, one to do interesting stuff
>> >needs to know also the rest of the API, but this is a
>> different point.  I
>> >also note that the API, in some sense, is getting simpler and simpler
>> after your large effort to turn the function calls in a
>> uniform layout.
>> >
>> >> ovl-<name>.5 ?
>>
>> I rather they be called something starting with "slap".
>> How about slapo-<name>.5?
>
> That was my first thought, actually. Works for me...

sound a bit weirdo in Italian ;) but it's also fine for me.

Ando.

-- 
Pierangelo Masarati
mailto:pierangelo.masarati@sys-net.it