Re: [wtp-dev] Provisional API take II

[Michael Elder <mdelder@xxxxxxxxxx>]

I like the idea. There's a list of standard Javadoc phrases in CVS [wst/components/common/development/JavaDocComments.txt].

 

I have recently updated the javadoc.xsl that exists in the wst.doc.isv plugin to use a few custom tags (explained in a HOWTO*.txt file within the plugin). We could add a <provisional /> element to that stylesheet that could then be used to generate a common disclaimer in the Javadoc package.xml overviews. This would be easier to standardize and maintain.

 

 

-------------------------------------------------------------------------

Kind Regards,

 

Michael D. Elder

Rational Studio / J2EE Tools Development     

IBM RTP Lab

Ext: (919) 543-8356

T/L: 441-8356

mdelder@xxxxxxxxxx

 

 

 

Tuesday, May 17, 2005 10:44 PM
To: wtp-dev@xxxxxxxxxxx
cc:
From: Timothy Deboer <deboer@xxxxxxxxxx>
Subject: [wtp-dev] Provisional API take II

Hi, 

The PMC has decided to 
defer feature support until 1.1, but make some API provisional in 1.0 (without 
moving to internal.provisional b/c of the risk this late in the cycle) so that 
we do not block ourselves from doing it. The suggested documentation for this 
provisional API was JavaDoc, component.xmls, and release documentation. 

Elson has pointed out that it makes sense 
to standardize the javadoc and use a common task tag that we can all optionally 
enable. To start the discussion, how about using the following notice, which was 
used by the Eclipse debug team in v1.0: 

 * <b>Provisional API:</b> This class/interface is part 
of an interim API that is still under development and expected to 
 * change significantly before 
reaching stability. It is being made available at this early stage to solicit 
feedback 
 * from pioneering 
adopters on the understanding that any code that uses this API will almost 
certainly be broken 
 * 
(repeatedly) as the API evolves. 

The 
only change I've made is switching the word "Note" to "Provisional API" to make 
it a better task tag. 

Thanks, 
Tim deBoer
WebSphere Tools - IBM Canada 
Ltd.
(905) 413-3503  (tieline 
969)
deboer@xxxxxxxxxx