ok , sorry

: Please don't set it to release-ready before everything is merged. This is how we track when the release branches are branched off. We don't want to do it too early.

Looks good, great work ! I have added comments in the individual tasks where necessary. I agree with the code snippets, having them would be nice, but doing so in a generic way would mean adding features to gdbus-codegen, which would be a project of its own. A tutorial is a good compromise.

Makes sense.

Too bad the code snippets are not (easily) available, maybe especially since they will be large (potentially lots of time/hassle saved). You are probably right that they are not expected, so it's likely not a hard requirement but something that could help us stand out (aka "delight feature").

However I do think a nice tutorial would be a good alternative, lacking this.

Here a summary of my research around D-Bus API documentation (more details in individual tasks).

I created all the tasks that I think we need. I haven't pinged you on them explicitly, but can you please review all the tasks referenced below?

So, let's start:

The convention is to specify D-Bus API via "introspectation data format" XML files.

--> Task covers this

These files should then be distributed in dev packages for other applications to compile against Mender D-Bus API(s).

--> Task for Debian
--> Task for Yocto

Then, with regards to the actual documentation:

We can generate our API docs based on the spec file with some post processing. As we want to have a markdown output, the post-processing is un avoidable.

I think we can aim to have something looking like this: https://core.docs.ubuntu.com/en/stacks/location/location-service/docs/reference/dbus-api

--> Task covers this

We also discussed about generating "code snippets" alongside the API docs. I have given this a fair amount of research, but 1) I couln't find any suitable tools to do this (most tools around DBus APIs center in wrapping the library code, but not generating user demo code) and 2) I could not find any other DBus API documentation site with code examples.

This made me conclude that the users that will read these docs will not expect such code snippets (if any, they will also be very large!) and I think we should drop it.

Instead, I suggest we can write a nice step by step tutorial writing a simple demo app in Python that uses our DBus API. Other languages could also be considered

--> Task covers the Python tutorial