Re: [platform-releng-dev] improved checking for internal references

[Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>]

This is certainly an issue regardless
of whatever technique is used.  Very much like Javadoc itself.  If
you change the code and not the doc, it gets out of date.  One thing
that we can do in this case however is further tooling support.  The
runtime for example has the potential to simply expose only the classes
which are declared as exposable.  Failure to keep the list correct
would then result in runtime errors.  Since PDE uses the same technology
under the covers, there is potential for the PDE classpath containers to
hide the classes at compile time resulting in red X's in *referencing*
code.  Referencers would then complain to the originator that the
classes they need are not exposed.  

This idea depends on some new function
in the JDT Core and the technique has yet to be tested but it seems like
it addresses most of the issues discussed here.  Note that this tooling
is not a complete cover of the tool proposed by Jeem.  The component.xml
has more information about subclassing etc.  This would simply ensure
that classes which should be exposed in some way, are.

Jeff

Peter Manahan/Toronto/IBM@IBMCA
Sent by: platform-releng-dev-admin@xxxxxxxxxxx

02/17/2005 11:49 AM

Please respond to
platform-releng-dev

To	platform-releng-dev@xxxxxxxxxxx
cc
Subject	Re: [platform-releng-dev] improved checking for internal references

I think the idea of the component.xml is great and something that has been
needed for a long time. But the potential for it to get out of date is
very likely. 

Perhaps if the component.xml was generated at build time.  I assume
the javadoc is built that way and since normally API is defined in javadoc
perhaps something could be added as a tag that allowed the generation of
the component.xml. Keeping all the information with the java files where
hopefully the API javadoc is kept up to date. 

Thanks,

-----------------------------------
Peter Manahan
IBM Rational Tools
Common Install
------------------------------------
manahan@xxxxxxxxxx 

platform-releng-dev-admin@xxxxxxxxxxx wrote on 17/02/2005 11:35:51 AM:

> I have some concerns about what this tool will mean in terms of process.
> 
> It seems that every team will be expected to update this file as public
> classes are added to their plug-ins.  They will also need to
update the file 
> if private internal classes are added.  If they fail to do so,
there also 
> doesn't seem to be any real way for them to realize that they have
forgotten 
> to do something.  As such, I am concerned that this will eventually
lead to 
> "component.xml" files that are significantly out-of-date.
> 
> Also, the creation of this file is not an insubstantial task.  For
example, 
> Platform/UI maintains about 2400 classes.
> 
> I would like to recommend that the use of this tool be put on hold
until it 
> can address some of these issues.  Ideally, the "component.xml"
file should 
> be optional.  Sane defaults should be obtainable by: parsing
the package 
> name, parsing javadoc comments, and make some assumptions about the
nature of 
> fragments.
> 
> 
> On Tuesday February 8 2005 05:52 pm, Jim des Rivieres wrote:
> > The tool takes as input a set of component definition files
> > (component.xml) that provides the following information for each
> > component:
> >
> > - what plug-ins are to be treated as a unit for the purposes
of drawing an
> > API boundary; all references between the plug-ins are considered
a private
> > matter (even if to internal packages)
> > - a list of packages that are to be considered API packages
> > - a list of classes and interfaces within the API package that
have
> > additional constraints on them (e.g., clients are not supposed
to
> > implement an API interface, instantiate an API class, or instantiate
an
> > API class)
> _______________________________________________
> platform-releng-dev mailing list
> platform-releng-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-releng-dev