Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [platform-dev] How to best document consumed OSGi/DS services? 
> Concretely, I want *extensibility* to be documented. So yes, I think
> it's about usage of some services.

ok

> Actually, it's the most important part IMO. The Platform usage of DS
> here and there is the extensibility, it needs to be documented.
but DS is only *one* way to consume a service, so I think this should not be limited to the ds topic. 

> I don't think we strongly need such specific javadoc annotations
> at the moment. Specific annotations were not required for extension
> points
but require statically crafted extension schemas... the counter-part for DS would be the component.xml that could for sure be scanned by some tool and generate whatever docs that are desired from. But as mentioned before, DS is just a way to consume services and even a DS component is not required to consume/produce *all* services in a declarative way.
So when it comes to OSGi Services the Service interface is where to define the contract, thus either class annotations or javadoc annotations seems most suitable for me.
If one wants to follow a "standard" I think the most normative would be the OSGi Specification itself, but this is nothing that could be generated out of code automatically I think.
For example take the "Config Admin Specification"[1], it contains several section describing how the service behaves, what consumers has to take into account and so on.
Further down, it describes the ServiceInterfaces e.g. the ConfigurationPlugin [2], taking a look at the source code one would see that it is a mixture of java annotations (e.g. @ConsumerType) as well as described Properties (e.g. CM_TARGET), or are annotated (e.g. CM_RANKING @since) that make up the contract of that services. How this service is consumed/provided (ds, service tracer, blueprint,..) doesn't matter.
Last but no least, it contains a package-info-class with some additional information where to find further information and the @Version annotation of what version this part is. 


[1] https://docs.osgi.org/specification/osgi.cmpn/7.0.0/service.cm.html
[2] https://docs.osgi.org/specification/osgi.cmpn/7.0.0/service.cm.html#org.osgi.service.cm.ConfigurationPlugin 


Am 23.03.21 um 08:49 schrieb Mickael Istria:
On Tue, Mar 23, 2021 at 6:24 AM Christoph Läubrich <laeubi@xxxxxxxxxxxxxx <mailto: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
    <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 <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 <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. 

_______________________________________________
platform-dev mailing list
platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev

Back to the top