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?
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

Back to the top