I’m gradually working on documenting Telepathy, the IM/real-time-communications toolkit, though I am currently still exploring the API rather than writing text, and I am only using occasional hours here and there for even that. The delay is more due to me than Telepathy. With the help of the Telepathy developers, I haveÂ completed some simple telepathy-glib examples, giving me a feel for the API. I can now start to write up some of the text.
Telepathy actually works and is full featured, and has many people working on it. That makes it very useful to many people.
But to be honest, the API feels frustrating so far and I think you’ll see what I mean when you look at those examples. I’ll continue trying to document it so people at least know what to do, even if what they have to do doesn’t seem very nice.
Apart from the many little annoyances, I think the API suffers greatly from extreme use of asynchronicity, instead of fighting to protect application developers from that. I think that’s partly due to the choice of D-Bus for the implementation, instead of just using a C library, forcing every method call to be asynchronous. There’s also a tendency for high-level actions to consist ofÂ multiple small (asynchronous) low-level steps, though that’s partly due to the awkwardness of simulating an object-orientated class hierarchy in a D-Bus API where even (the equivalent of) a cast is asynchronous, and a consequence of needing to discover interfaces at runtime, due to inconsistent interface coverage by the various plugins (connection managers). There’s also a tendency to expose the (naturally asynchronous) client-server network behavior of the protocols directly in the API instead of combining and hiding multiple network back and forth behind simpler API, though the new TpContact class does a lot of work in the background.
However,Â I have not yet explored the whole API and don’t yet have a full sense of the common ways that the API is used, so my judgement could conceivably be wrong. I also suspect that it could be much worse.