Re: [pde-dev] Re:[api tooling] Re: Using component.xml as a starting poi

[Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>]

slightly off the original topic but
we should rationalize these tags in consideration of the markup needed
on members.  For example, @nosubclass could be @noextend and then
the same tag could be used to mark up types and method (ones that subtypes
should not override).  for this example it may actually be better
to have an @nooverride tag but the point is before people start running
around putting in tags, it would be good to get the big picture of all
required tags to the tag set is coherent.

As for API, SPI etc, it seems the only
one that needs markup is SPI.  For that there are two parts, the types/methods/...
that make up the SPI and then some way of noting that some wad of code
A is indeed a service provider and show should be able to reference B's
SPI.  Not sure how we should do that.  Thoughts?

Jeff

Elizabeth B Silberg <silberg@xxxxxxxxxx>
Sent by: pde-dev-bounces@xxxxxxxxxxx

10/30/2007 07:04 PM

Please respond to
"Eclipse PDE general developers list." <pde-dev@xxxxxxxxxxx>

To	"Eclipse PDE general developers list." <pde-dev@xxxxxxxxxxx>
cc
Subject	Re: [pde-dev] Re:[api tooling] Re: Using component.xml as        a        starting        point

This makes sense to me, too.  To bring this into the plain java world,
are you planning on adding javadoc tags to specify API, SPI, etc or just
the special cases listed on the WIKI:

• Update @since tags for newly added classes, interfaces, methods, etc.
• Provide new javadoc tags and code assist to annotate types with special restrictions:
  • @nosubclass - This class is not intended to be subclassed.
  • @noinstantiate - This class is not intended to be instantiated.
  • @noimplement - This interface is not intended to be implemented by clients.
  • @noreference - This type is not intended to be referenced by clients.
  
  I realize these aren't your main targeted consumers, but we've discussed that they should be able to use the tooling as well.  If they shouldn't use javadoc tags to specify API, SPI, etc, when will an alternative to manifest files as inputs be defined?
  
  Thanks,
  Elizabeth
  
  
  
  
  Chris Aniszczyk/Austin/IBM@IBMUS
  Sent by: pde-dev-bounces@xxxxxxxxxxx

  10/29/2007 06:18 PM
  

  Please respond to
  "Eclipse PDE general developers list." <pde-dev@xxxxxxxxxxx>

  To	"Eclipse PDE general developers list." <pde-dev@xxxxxxxxxxx>
  cc
  Subject	Re: [pde-dev] Re:[api tooling] Re: Using component.xml as a        starting        point

  
  
  
  
  
  
  
  
  +1, this makes sense... shouldn't be that bad to tool the javadoc tags.
  
  Cheers,
  
  ---
  Chris Aniszczyk | IBM Lotus | Eclipse Committer | http://mea-bloga.blogspot.com | +1.860.839.2465
  
  Jeff McAffer ---10/29/2007 08:06:07 PM---moving this to the PDE list... I agree. With both of you actually. I tihnk that Olivier's original

  From:	Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>
  To:	pde-dev@xxxxxxxxxxx
  Date:	10/29/2007 08:06 PM
  Subject:	[pde-dev] Re:[api tooling] Re: Using component.xml as a starting point

  
  
  

  ---

  
  
  
  
  moving this to the PDE list...
  
  I agree. With both of you actually. I tihnk that Olivier's original post was proposing a one-off tool that would update the javadoc as appropriate and mark places where there was an issue. so you are agreeing as well :-)
  
  Jeff
  
  Darin Wright/Ottawa/IBM@IBMCA
  Sent by: equinox-dev-bounces@xxxxxxxxxxx

  10/29/2007 04:54 PM
  
  

  Please respond to
  Equinox development mailing list <equinox-dev@xxxxxxxxxxx>

  
  

  To	equinox-dev@xxxxxxxxxxx
  cc
  Subject	[equinox-dev] [api tooling] Re: Using component.xml as a starting point

  
  
  
  
  
  
  
  
  
  
  
  We are getting close the chicken and egg problem here....
  
  When it's time for developers to start using the tooling, we want to make it easy - so yes, it would be handy to have a tool that inserts javadoc tags based on existing component XMLs. I think the tags "replace" component.xml - so I don't think we should have tooling to keep the two in synch. I would see this as a "one off" tool to get started. For that reason, I don't think we would want to create markers as it would require "active" tooling to keep the two in synch. As well, we'd have to have some mechanism for knowing if the "component.xml" should be considered as the "source" for tag generation, or the "target" for caching existing tags. It feels awkward to have duplicated information in the IDE - when the user can edit both. Would it be better to have a tool/action/wizard that processes the component XML and generates a report for issues (rather than makers)?
  
  Does anyone think that we should have tooling to maintain the "component.xml" files? I'd rather just use the javadoc tags as the "source" of the information in the workspace. At build time, we could also use source to generate that part of our API description.
  
  Darin
  Olivier Thomann/Ottawa/IBM

  10/29/2007 02:17 PM

  
  

  To	Darin Wright/Ottawa/IBM@IBMCA, Michael Rennie/Ottawa/IBM@IBMCA, Jeff McAffer/Ottawa/IBM@IBMCA
  cc
  Subject	Using component.xml as a starting point

  
  
  
  
  
  
  
  
  
  
  
  
  Hi,
  
  We should use the existing component.xml file for each plugin in the SDK to "tag" the corresponding types with the appropriate javadoc tag.
  So the tool would take the component.xml and check all the API types inside the workspace.
  The existing text that describes the API usage would be replaced with the corresponding tag and for the API type where the existing text is not an exact match, the tag would be added and a marker created to remember that this file should be double-checked.
  The "new" API types that have been added since the component.xml was created should also be marked to be double-checked.
  
  This could allow us to get a "good" baseline.
  
  What do you think?
  
  Olivier _______________________________________________
  equinox-dev mailing list
  equinox-dev@xxxxxxxxxxx
  https://dev.eclipse.org/mailman/listinfo/equinox-dev
  _______________________________________________
  pde-dev mailing list
  pde-dev@xxxxxxxxxxx
  https://dev.eclipse.org/mailman/listinfo/pde-dev
  
  _______________________________________________
  pde-dev mailing list
  pde-dev@xxxxxxxxxxx
  https://dev.eclipse.org/mailman/listinfo/pde-dev
  _______________________________________________
  pde-dev mailing list
  pde-dev@xxxxxxxxxxx
  https://dev.eclipse.org/mailman/listinfo/pde-dev