[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
Re: [platform-dev] [osgi-wg] How to document OSGi extensibility?
|
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
<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
To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev
_______________________________________________
osgi-wg mailing list
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