Tango quibbles - please write tickets so we can track them

[kris]

Matti Niemenmaa wrote:
> kris wrote:
>> Lutger wrote:
>>> kris wrote:
>>>> Yes, the doc could be better overall. Some of it is just awesome,
>>>> whilst some of it kinda sucks (my writing skills, for example). 
>>> [OT] No, your writing skills don't suck at all, but I think you did
>>> place the bar a bit high with that io chapter. Mainly by assuming
>>> readers are familiar with this kind of terminology.
>> OK, thank you. We'll get that fixed :)
> 
> I agree. In particular because Tango uses different terminology than just about
> all other languages/libraries (streams vs conduits, almost everything is a
> buffer instead of the stream doing the buffering), the I/O chapter should start
> from the very basics and have useful examples.
> 
> It took me a long time to figure out the idioms around Tango I/O to the point
> that I could write generic I/O code for a library, for example. For the C++ STL,
> use std::istream and std::ostream. For Phobos, use std.stream.InputStream and
> OutputStream.
> 
> After reading the (original version of the) Tango reference manual, I had no
> clue. "Conduits, presumably, but what about Buffers? Do they need separate
> support, or should I just take the Conduit the Buffer is wrapped around? But
> won't that bypass the buffering?" Things like that.

All good points. This is partly why we're always asking for help with 
the doc (in each release announcement)


> Of course, it helps that the system has undergone a few redesigns in its short
> life (the additions of InputStream + OutputStream, for instance). The reference
> manual seems to have improved, too.

Glad to hear there's been some progress


> There's still some stuff I don't quite get, though. For instance, IConduit and
> IBuffer: everything seems to inherit from Conduit or Buffer, so why have the
> basic interfaces? Expanding on the reasons behind the whole design (and the
> terminology) might be a good idea.

Tango often uses interfaces to decouple implementation: you can operate 
via an interface (handed to you as an argument) without importing any 
concrete implementation. In a library of any size, this really helps to 
avoid tight- or cross-coupling.

It means, for example, that other (more traditional) interfaces can rely 
on remaining 'pure', in that they only ever import other interfaces and 
not some specific implementation code.

We once looked at removing IConduit and IBuffer, but decided they were 
just too useful. We're quite picky about introducing interfaces, though 
... don't wish to overuse use them.