Re: [wtp-dev] API Documentation publish process

[Michael Elder <mdelder@xxxxxxxxxx>]

Arthur,

 

   I agree with the need to keep the javadoc at a stable location. I personally like the ".../webtools/<subproject/api/index.html" location since it's short and easy to remember. Perhaps our build process should just automatically update that location with the latest version?

 

   The J2EE Tools team will go ahead and update our javadoc with @since -- perhaps Tim could do the same for Server Tools?

 

   Another piece that I'd like to propose is that all API package summaries include a UML diagram of the exposed API (as in modulecore) to give our consumers a quick overview of what's available. Those internal to IBM should able to do this quickly with RSA and perhaps we could find another opensource UML2 editor for non-IBMer-types. Any thoughts?

 

 

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

Kind Regards,

 

Michael D. Elder

Rational Studio / J2EE Tools Development     

IBM RTP Lab

Ext: (919) 543-8356

T/L: 441-8356

mdelder@xxxxxxxxxx

 

 

 

Friday, February 18, 2005 6:07 PM
To: wtp-dev@xxxxxxxxxxx
cc: wtp-dev@xxxxxxxxxxx, wtp-dev-admin@xxxxxxxxxxx
From: Arthur Ryman <ryman@xxxxxxxxxx>
Subject: Re: [wtp-dev] API Documentation publish process

Michael, 

Thx. The Javadoc looks great. I'd like to 
ensure that we keep the Javadoc at a stable and predictable URL so that we have 
the opportunity to link to it from other documents, e.g. API scanning 
reports. 

Earlier today, Jeffrey held 
an API scanning meeting and we kicked around some ideas for automatically 
checking the quality of the Javadoc. For example, we need to make sure that 
Javadoc is complete for all API types. This means all parameters must be 
documented via @param and @return, and  all exceptions via @throws. 

Also, we should follow Jeem's 
guideline of using an @since tag on all API classes. All WTP 1.0 packages and 
classes should have: 

@since 
1.0 

Method level @since tags should 
only be used when methods are added to an existing class in future 
releases. 

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
intranet: 
http://labweb.torolab.ibm.com/DRY6/

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

02/18/2005 05:35 PM

Please respond to
wtp-dev

To	wtp-dev@xxxxxxxxxxx
cc
Subject	Re: [wtp-dev] API Documentation publish process

Arthur, 
  
   My teammate, Jason Sholl, will be coordinating 
the process for JST and updating the doc.isv plugin with the J2EE team's 
packages. 
  
------------------------------------------------------------------------- 
Kind Regards, 
  
Michael D. Elder 
Rational Studio / J2EE Tools 
Development     
IBM RTP Lab 
Ext: (919) 543-8356 
T/L: 441-8356 
mdelder@xxxxxxxxxx 
  
  
  
Friday, February 18, 2005 5:32 PM
To: wtp-dev@xxxxxxxxxxx
cc: 
From: Arthur Ryman <ryman@xxxxxxxxxx>
Subject: Re: [wtp-dev] API 
Documentation publish process


Michael, 

Thx. Please coordinate with JST to set up a similar directory. 

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
intranet: http://labweb.torolab.ibm.com/DRY6/

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

02/18/2005 04:02 PM

Please respond to
wtp-dev

To	wtp-dev@xxxxxxxxxxx
cc
Subject	[wtp-dev] API Documentation publish process

Extended 
Team:

    There is a new directory under wst/components named 
"doc" wherein the
new "org.eclipse.wst.doc.isv" plugin lives. This plugin has 
an Ant script
named "javadoc.xml" that handles the details of building the 
Javdoc for all
WST components.

    To add your API to the 
generation process, update the
org.eclipse.wst.doc.isv/javadoc.properties 
file to include your (1) source
folder container(s) for API, (2) API packages 
to document, and (3) the bin
directory of the plugin. Each of these paths 
assumes that
org.eclipse.wst.doc.isv is peer to all other plugins that 
contain API.

    To create a package description file, begin 
with
org.eclipse.wst.doc.isv/template_package.xml and put it in your API 
package
as "package.xml". The first sentence should be a general summary of 
the
package -- this will appear on the overview page beside the package 
name.
This file has some standard templates that have been used through the 
J2EE
doc process, and we would encourage other teams to adopt these 
for
consistency. There is a comment in the file as well that must be 
removed
before XSLT will run on the file. The comment includes information 
about
how to link images directly into the Javadoc.

    If 
you'd like to see an example of how this is done, 
see
wst/common/org.eclipse.wst.common.modulecore/modulecore/org.eclipse.wst.common.modulecore.


  
  The API are available on the website now 
(
http://www.eclipse.org/webtools/wst/api/index.html) but I'm not 
currently
anticipating that this part of the publish process be a long term 
solution.
However, this will allow us to make them available to users though 
until
the build plan is fully hammered 
out.





-------------------------------------------------------------------------
Kind 
Regards,

Michael D. Elder
Rational Studio / J2EE Tools 
Development
IBM RTP Lab
Ext: (919) 543-8356
T/L: 
 441-8356
mdelder@xxxxxxxxxx


_______________________________________________
wtp-dev 
mailing 
list
wtp-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/wtp-dev