On Tue, Mar 23, 2021 at 9:47 AM Christoph Läubrich <[email protected]> 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 <[email protected]> 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 > [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 > > <[email protected] <mailto:[email protected]>> 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 > > [email protected] > > To unsubscribe from this list, visit > https://www.eclipse.org/mailman/listinfo/platform-dev > > > _______________________________________________ > platform-dev mailing list > [email protected] > To unsubscribe from this list, visit > 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 [email protected] To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
