Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] Provisional API take II


A <provisional/> tag would tie the semantics to our stylesheet. A @provisional tag seems more Javadoc friendly and we could still insert our own text.

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@xxxxxxx

Michael Elder <mdelder@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

05/18/2005 09:31 AM

Please respond to
"General discussion of project-wide or architectural issues."

"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
Re: [wtp-dev] Provisional API take II

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    
Ext: (919) 543-8356
T/L: 441-8356
Tuesday, May 17, 2005 10:44 PM
To: wtp-dev@xxxxxxxxxxx
From: Timothy Deboer <deboer@xxxxxxxxxx>
Subject: [wtp-dev] Provisional API take II


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.


Tim deBoer
WebSphere Tools - IBM Canada Ltd.
(905) 413-3503  (tieline 969)
wtp-dev mailing list

Back to the top