3 ms·

>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 fr

>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'.

viraptor 11y ago
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.
- gillianseed 11y ago
  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 ?
  - simoncion 11y ago
    > 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.
- DavidNielsen 11y ago
  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.
  - viraptor 11y ago
    Your first sentence seems to contradict the docs... which still don't describe "all the stable parts".
  - geofft 11y ago
    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.

viraptor 11y ago

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.

gillianseed 11y ago
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 ?
- simoncion 11y ago
  > 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.
DavidNielsen 11y ago
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.
- viraptor 11y ago
  Your first sentence seems to contradict the docs... which still don't describe "all the stable parts".
- geofft 11y ago
  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.