"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?"
Whiteboard is more than just getting services injected. So I would also not
use @Whiteboard for a documentation annotation.
Christoph Läubrich <lae...@laeubi-soft.de> schrieb am Fr., 22. Jan. 2021,
16:48:
> 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
> >>
> >>
> >> Am 22.01.21 um 15:56 schrieb Mickael Istria:
> >>>
> >>>
> >>> On Fri, Jan 22, 2021 at 3:42 PM Christoph Läubrich
> >>> <lae...@laeubi-soft.de <mailto:lae...@laeubi-soft.de>> 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@eclipse.org
> >>> To unsubscribe from this list, visit
> >>> https://www.eclipse.org/mailman/listinfo/platform-dev
> >>>
> >> _______________________________________________
> >> osgi-wg mailing list
> >> osgi...@eclipse.org
> >> To change your delivery options, retrieve your password, or
> >> unsubscribe from this list, visit
> >> https://dev.eclipse.org/mailman/listinfo/osgi-wg
> >
> _______________________________________________
> platform-dev mailing list
> platform-dev@eclipse.org
> To unsubscribe from this list, visit
> https://www.eclipse.org/mailman/listinfo/platform-dev
>
_______________________________________________
platform-dev mailing list
platform-dev@eclipse.org
To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev
