Re: [platform-dev] How to best document consumed OSGi/DS services?

[Mickael Istria <mistria@xxxxxxxxxx>]

On Tue, Mar 23, 2021 at 6:24 AM Christoph Läubrich <laeubi@xxxxxxxxxxxxxx> wrote:

I'm not sure what you have in mind. DO you like to document the *usage*
of DS?

Concretely, I want *extensibility* to be documented. So yes, I think it's about usage of some services.

as mentioned earlier I would expects documentation at the service
interface itself.

Right.

 

That platform uses DS to consume services is just an
implementation detail and doesn't bother the provider much.

Actually, it's the most important part IMO. The Platform usage of DS here and there is the extensibility, it needs to be documented.

Such documentation then could of course use javadoc annotations that
then could be present in the html output as well see
https://maven.apache.org/plugins-archives/maven-javadoc-plugin-2.8.1/examples/tag-configuration.html

I don't think we strongly need such specific javadoc annotations at the moment. Specific annotations were not required for extension points, so I don't think they should be necessary for services.

Concretely, I think we need a page similar to https://help.eclipse.org/2021-03/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fextension-points%2Findex.html but listing the service classes and their usage in some extensibility contracts.

I've opened https://bugs.eclipse.org/bugs/show_bug.cgi?id=572207 on that matter. This is IMO critical that we get a "minimal viable product" of such documentation before we start growing the extensibility of Platform via services.