Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] API Documentation publish process


Michael,

Yes, I think the build should update the Javadoc. However, we should discuss if the current CVS driven Web site is the right approach. It seems wrong to me to put a lot of generated content into CVS. Maybe we should consult our Webmaster on this first?

Thx for adding the @since tags.

I am in favour of having an API overview document, and I encourage you to use UML if you believe that's the best way to convey the content. However, I'd prefer to let the API developers decide on how they want to write the overview. Other types of diagram might be more suitable in some cases. Or maybe no diagram at all.

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 06:15 PM

Please respond to
wtp-dev

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





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



Back to the top