Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [platform-dev] [osgi-wg] How to document OSGi extensibility? 
Look at it this way:
I like to have autocompletion and I don't care if eclipse uses GenericEditor or whatever.
If I implement it (because I know autocompletion can be done this way because of documentation/blogbpost whatever) and it does not work in GE I can raise a bug/feature request to add support for it, but as first I literally don't care how the item is named :-) 

Thats currently a big issue for newcommers IMO that one has first find out:
- What is the component that is responsible for feature X
- What is the way/ext points to enhance this particular component
- Are there other components to consider because this one just uses features from Y (go back to start)
Wouldn't it be nice to have just the interface of interest declaring "implement+register me for autocompletion"? Sure if you are familiar with the whole eco-system it might be "obvious" what to do. But to come to a recent problem "how to add formatting capabilities to GE" it seems not so obvious even for long-time committer (or its so trivial nobody beside Mickael bother to answer)... it would be incredible easy to implement "DocumentFormater", register it for the content type and formatting wold just work in GE or whatever other editor that is capable of that given content-type, maybe even simple text-boxes... 

Am 23.01.21 um 11:37 schrieb Wim Jongman:

Look at it this way:
The documentation in the service interface will NOT say "You can implement me and the generic editor will consume me." 
, because it does not care who consumes it.
So what is the reason to start implementing it? It is always because they want to extend the GE (or any other consumer of the service). So in my opinion that is where the docs should be. 

Cheers,
Wim
On Sat, Jan 23, 2021 at 8:33 AM Christoph Läubrich <laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>> wrote: 

      > Mostly because the documentation is the wrong way around. We want to
      > make clear from the generic editor user's POV that a whiteboard
      > pattern can be used

    Actually the nice thing about whiteboardpattern is that the provider of
    the service has not to care about its consumers (in contrast to
    extension point semantics).

    That mean, instead of implementing content assist *for* generic editor,
    my plugin can simply *offer* content assist for a given content type,
    anyone is free to use that (including generic editor) but not
    limited to
    and if the API is well designed.

    That means instead we can documenting/telling people if they want to
    provide content assist for a content-type they can simply register the
    serviceinterface. If there are other places that could use
    content-assist for a given content-type we dont need to tell people we
    simply need to consume the service there and all is set!
    Even external plugins can use the service without an need for adding
    another extensionpoint and asking people to implement that.

    So from a user POV it makes much more sense to document at the service
    interface the intent to use this as a "WhiteBoardService".


    Am 22.01.21 um 20:31 schrieb Wim Jongman:
     > The annotations idea is very creative but I don't think it is the
    answer
     > to Mickaels question.
     >
     > Mostly because the documentation is the wrong way around. We want to
     > make clear from the generic editor user's POV that a whiteboard
    pattern
     > can be used to inject code, not from the interface. Besides, who
    would
     > know that that annotation even exists?
     >
     > IMO, Tom has the perfect simple answer. We should add to the
    javadoc of
     > generic editor and to the extension points docu the an
    alternative way
     > of consuming.
     >
     > Cheers,
     >
     > Wim
     >
     >
     > On Fri, Jan 22, 2021 at 4:48 PM Christoph Läubrich
     > <laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>
    <mailto:laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>>> wrote:
     >
     >     As its about to document a service interface is intended to
    be consumed
     >     by the (OSGi) Whiteboard pattern why should it be a bad name? :-)
     >
     >     The context is the following:
     >
     >     There is a service interface that is consumed by some other
    component
     >     using the Whiteboardpattern.
     >
     >     The question was: How can we clearly document that it is
    supposed to be
     >     consumed and what service properties are meant to be present.
     >
     >     Thats similar to what the MetaDataService tries to provide for
     >     component
     >     configurations.
     >
     >     My very simple first proposal was to have an
     >
     >     @Whiteboard
     >
     >     annotation on the service interface that documents the
    possible service
     >     properties as strings that map to final static fields. I
    attached an
     >     example here
     >
     >     ------------------
     >
     >     @Whiteboard(properties = {"SERVICE_PROPERTY_ADAPTABLE_CLASS",
     >     "SERVICE_PROPERTY_ADAPTER_NAMES"})
     >     public interface IAdapterFactory {
     >
     >              /**
     >               * Service property to use when registering a factory as
     >     OSGi-service
     >     to declare the adaptable class type, this is a
     >     multi-string-property, if
     >     more than one is given the factory will be register multiple
    times
     >               * @since 3.14
     >               */
     >              static final String SERVICE_PROPERTY_ADAPTABLE_CLASS =
     >     "adaptableClass"; //$NON-NLS-1$
     >
     >              /**
     >               * Optional service property to use when registering a
     >     factory as
     >     OSGi-service to declare the possible adapter types. If the
    property is
     >     given, the service is only queried when actually required,
    this is a
     >     multi-string-property.
     >               * @since 3.14
     >               */
     >              static final String SERVICE_PROPERTY_ADAPTER_NAMES =
     >     "adapterNames";
     >     //$NON-NLS-1$
     >
     >
     >     ....
     >
     >
     >
     >     Am 22.01.21 um 16:39 schrieb Jürgen Albert:
     >      > Providing some kind of Service and/or annotation to provide
     >      > documentation aether at runtime or at development time
    crossed my
     >     mind
     >      > as well and could be a good Idea.
     >      >
     >      > It seems that I miss a bit of context here however. What
    are you
     >      > actually proposing?
     >      >
     >      > BTW: With the little context I have, @Whiteboard would be
    a bad name
     >      > choice, because the Whiteboard concept is a bit loaded in the
     >     OSGi Context.
     >      >
     >      > Regards,
     >      >
     >      > Jürgen.
     >      >
     >      > Am 22/01/2021 um 16:04 schrieb Christoph Läubrich:
     >      >> OSGi Alliance was moved to Eclipse last year... :-)
     >      >>
     >      >> OSGi already defines some annotations for the package
    level see
     >     , OSGi
     >      >> DS makes heavy use with great success of annotations.
     >      >>
     >      >> The problem is more that the Eclipse way of thinking is
    sometimes
     >      >> incompatible with standard OSGi ;-)
     >      >>
     >      >> But I think if a draft for a @Whiteboard annotation could be
     >     provided
     >      >> in Eclipse it might become the reference-implementation of an
     >     official
     >      >> Eclipse specification later on :-)
     >      >>
     >      >> [1]
     >      >>
     >
    https://blog.osgi.org/2018/07/osgi-r7-highlights-bundle-annotations.html
    <https://blog.osgi.org/2018/07/osgi-r7-highlights-bundle-annotations.html>
>  <https://blog.osgi.org/2018/07/osgi-r7-highlights-bundle-annotations.html <https://blog.osgi.org/2018/07/osgi-r7-highlights-bundle-annotations.html>> 
     >      >>
     >      >>
     >      >> Am 22.01.21 um 15:56 schrieb Mickael Istria:
     >      >>>
     >      >>>
     >      >>> On Fri, Jan 22, 2021 at 3:42 PM Christoph Läubrich
     >      >>> <laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>
    <mailto:laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>>
     >     <mailto:laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>
    <mailto:laeubi@xxxxxxxxxxxxxx <mailto:laeubi@xxxxxxxxxxxxxx>>>> wrote:
     >      >>>
     >      >>>     Good point! I'd like to enhance my annotation idea
    in the
     >      >>> following way:
     >      >>>
     >      >>>     @Whiteboard(extensions = {
>      >>> "org.eclipse.ui.genericeditor.contentAssistProcessors" 
     >      >>>        }
     >      >>>        properties = {"xyz"}
     >      >>>        }
     >      >>>     )
     >      >>>
     >      >>>     that way it would be possible to automatically read the
     >     meta-data
     >      >>> and
     >      >>>     transform them into help or whatever...
     >      >>>
     >      >>>
     >      >>> Eclipse Platform should avoid the funk of building and
    relying on
     >      >>> Eclipse-specific documentation annotations for OSGi. It
    looks
     >     like in
     >      >>> this case, it's more interesting to just bring the idea
    to the
     >     OSGi
     >      >>> Alliance so it can become specified or shared with other
    OSGi
     >      >>> projects to identify the best solution in a standard-ish
    way; and
     >      >>> then Eclipse Platform could start using them.
     >      >>> Concretely, generating documentation is a difficult
    task, see how
     >      >>> javadoc or PDE extension point doc-gen are complex; we don't
     >     want to
     >      >>> start dealing with such extra complex new problem in
    Platform.
     >      >>>
     >      >>> Note that 1 issue introduced by the idea of documenting
    on the
     >      >>> interface is that it kinds of break the layers: the
     >      >>> IContentAssistProcessor interface is not aware of Generic
     >     Editor, so
     >      >>> it looks like we'd suddenly have to make it kind of aware of
     >     it, at
     >      >>> least in the doc, creating a (very soft, not technically
    binding)
     >      >>> dependency cycle. That seems undesired to me.
     >      >>>
     >      >>> _______________________________________________
     >      >>> platform-dev mailing list
     >      >>> platform-dev@xxxxxxxxxxx
    <mailto:platform-dev@xxxxxxxxxxx> <mailto: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>
     >     <https://www.eclipse.org/mailman/listinfo/platform-dev
    <https://www.eclipse.org/mailman/listinfo/platform-dev>>
     >      >>>
     >      >> _______________________________________________
     >      >> osgi-wg mailing list
     >      >> osgi-wg@xxxxxxxxxxx <mailto:osgi-wg@xxxxxxxxxxx>
    <mailto:osgi-wg@xxxxxxxxxxx <mailto:osgi-wg@xxxxxxxxxxx>>
     >      >> To change your delivery options, retrieve your password, or
     >      >> unsubscribe from this list, visit
     >      >> https://dev.eclipse.org/mailman/listinfo/osgi-wg
    <https://dev.eclipse.org/mailman/listinfo/osgi-wg>
     >     <https://dev.eclipse.org/mailman/listinfo/osgi-wg
    <https://dev.eclipse.org/mailman/listinfo/osgi-wg>>
     >      >
     >     _______________________________________________
     >     platform-dev mailing list
     > platform-dev@xxxxxxxxxxx <mailto:platform-dev@xxxxxxxxxxx>
    <mailto: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>
     >     <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>
     >
    _______________________________________________
    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
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev

Back to the top