[
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?
|
I think the most simple aproach would be to makr Interfaces that are
consumed by the Platform with @ProviderType [1], this could then be
scanned by tools and generate the list you have mentioned automatically.
[1]
https://docs.osgi.org/specification/osgi.core/7.0.0/framework.api.html#org.osgi.annotation.versioning
Am 28.03.21 um 07:35 schrieb Mickael Istria:
On Tue, Mar 23, 2021 at 9:47 AM Christoph Läubrich
<laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>> wrote:
but DS is only *one* way to consume a service, so I think this should
not be limited to the ds topic.
Right. The scope is more than DS, it's really about "extensibility
provided by OSGi services". This could simply start as a list of
class+link to Javadoc in the documentation. What do you think?
On Tue, Mar 23, 2021 at 9:47 AM Christoph Läubrich
<laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>> wrote:
> 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
<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
<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>
<mailto: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>
>
<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>
>
<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>
> <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 <mailto:platform-dev@xxxxxxxxxxx>
> To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev
<https://www.eclipse.org/mailman/listinfo/platform-dev>
>
_______________________________________________
platform-dev mailing list
platform-dev@xxxxxxxxxxx <mailto:platform-dev@xxxxxxxxxxx>
To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev
<https://www.eclipse.org/mailman/listinfo/platform-dev>
--
Mickael Istria
Eclipse IDE <https://www.eclipse.org/downloads/eclipse-packages/>
developer, for Red Hat Developers <https://developers.redhat.com/>
_______________________________________________
platform-dev mailing list
platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev