[eclipse.org-architecture-council] [Bug 256448] New: How to treat proper

[bugzilla-daemon@xxxxxxxxxxx]

https://bugs.eclipse.org/bugs/show_bug.cgi?id=256448  
Product/Component: Community / Architecture Council
           Summary: How to treat propertyTesters from an API point of view
           Product: Community
           Version: unspecified
          Platform: PC
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P3
         Component: Architecture Council
        AssignedTo: eclipse.org-architecture-council@xxxxxxxxxxx
        ReportedBy: martin.oberhuber@xxxxxxxxxxxxx
                CC: Darin_Wright@xxxxxxxxxx, zx@xxxxxxxxx


Eclipse Platform provides the
  org.eclipse.core.expressions.propertyTesters
extension point that allows plug-ins to register properties which can be
checked from various extensions such as menus, launch configurations and the
like.

I'm looking for best practices on documenting and versioning such properties.

1. Creators of menus who want to test properties need to know what properties
   are available, i.e. what ID's of properties are defined by the various 
   plug-ins available in the target platform. They may also look for
   documentation on each available property. How should providers of 
   propertyTester extensions document their available properties? Does
   anybody on the AC already document this, and how? What should be the
   Best Practice

2. Is there an existing bug on PDE that requests auto-generation of the 
   respective documentation from the extensions, as well as "browse" 
   functionality in the plug-in manifest editor to show available properties
   at those places where a property can be checked?

3. In my view, propertyTester extensions are part of the API of a plug-in.
   How do we treat plug-in versioning for such extensions? I'd think that
   addition of a new proeprtyTester extension would require reving up the
   minor version of a bundle, and users of propertyTester extensions should
   require the minimum version of a bundle that introduced the corresponding
   Property.
   Is it possible to add API Tooling for propertyTester extensions?
   Is there an existing bug which requests this?

I guess that there are more similar cases of API exposed not through Java but
through plugin.xml markup (basically every new extension point, and every new
slot in an extension point expose new API, but @since versions are currently
only available on a coarse granularity and API tooling does not check them.

In the propertyTester case, there is even a single slot only to list multiple
properties that happen to be provided by a single IPropertyTester
implementation. I think that this is bad practice in terms of traceability of
API additions, and I'd propose to split these up into separate slots, each of
which can be marked with an @since tag separately.

What do other AC members think about this?


-- 
Configure bugmail: https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the assignee for the bug.