Hacker News Reader

Comment by gillianseed | Hacker News Reader

I googled for systemd api interfaces and this was the first thing I got:

http://www.freedesktop.org/wiki/Software/systemd/InterfacePo...

That documentation / list is interesting. They say that logind is fully documented for example. But if you follow the link, you get things like:

    CreateSession(in  u arg_0,
                    in  u arg_1,
                    in  s arg_2,
                    in  s arg_3,
                    in  s arg_4,
                    in  s arg_5,
                    ...

With no further explanation, apart from one paragraph summary of who shouldn't call it.

I remember someone complaining about that years ago already. Apparently nothing changed.

>With no further explanation, apart from one paragraph summary of who shouldn't call it.

The CreateSession description states that it should never be called from the clients, but instead be handled through PAM, so assume this is why they don't describe the arguments for this one call, while all the other method arguments and return values are described under 'Methods'.

That's hardly "fully documented" though, isn't it?

What I mean specifically is that they document the client interface only, not the full interface needed for a complete replacement.

Well since it's one single method that's not documented, and they say you should not call it from a client, I assume they want to make it clear by not exposing the arguments in the client api documentation.

If you want to re-implement logind you will invariably read the logind source code anyway, where the call arguments are described.

You said there been a complaint about this, was there a discussion you can point me to ?

> If you want to re-implement logind you will invariably read the logind source code anyway...

1) Does this mean that you consider software's source code to be adequate documentation of an API and its behavioral contracts?

2) There's this saying that goes something like "You never know that you have a good API until you've created three independent implementations of it.". It's very difficult to create an independent implementation of an API if the primary documentation of important parts of that API's behavior is the source code that implements that API.

They have very well defined documentation for all the stable parts of the API, their code is modern and quite readable. In addition to this Lennart is good at publishing lengthy explanatory blogposts aimed at system administrators. Finally they have done a truly admirable job building a community and explaining the why's and how's of their project. This is evident in the fact that there is now a systemd conference coming up.

If this fails the test, I suggest that it is a marvelous failure which every project should strive to emulate. To suggest that systemd is poorly documented indicates an insufficient exposure to the sad reality of most Open Source projects where "our unmaintained, outdated, bug riddled code base is the documentation" is the best case answer to the question of documentation.

Your first sentence seems to contradict the docs... which still don't describe "all the stable parts".

Having done distro-maintenance work that needed to be compatible with both systemd and upstart, I've read the explanatory blog posts and found them wonderful, and I've also found the detailed API documentation lacking in spots.

There are a lot of praiseworthy things about systemd and its approach to documentation. The blog posts are definitely one of them. That doesn't mean everything is praiseworthy, that there's no room for improvement, or that complaints about things not being documented are illegitimate or inappropriate.

Reply on news.ycombinator.com