Re: [wtp-dev] ISV documentation and API docs/Javadoc - ACTION REQUIRED

[Lawrence Mandel <lmandel@xxxxxxxxxx>]

Hi Amy,

The component approach Susan outlined
would all be contained in the WST and JST ISV plugins. (These two plugins
should remain separate for those ISV's that are interested in the WST but
not the JST.) Separating components within the plugin should allow those
extending the platform to quickly and easily find the documentation they
are looking for.

As far as the JavaDoc goes, if it is
more complicated to separate it out it can be left as is at this point.
The separate component topics within the ISV help books can still be used
for component specific documentation.

Lawrence Mandel

Software Developer
IBM Rational Software
Phone: 905 - 413 - 3814   Fax: 905 - 413 - 4920
lmandel@xxxxxxxxxx

Amy Wu <amywu@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

07/06/2005 03:56 PM

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

To	"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc
Subject	Re: [wtp-dev] ISV documentation and API docs/Javadoc - ACTION REQUIRED

It looks like Eclipse has 
org.eclipse.platform.doc.isv 
org.eclipse.jdt.doc.isv 

and for the most part, all isv doc is stored there.  There are some
misc documents, like samples that are stored in their own separate plugins
instead of in the isv plugins.  And it looks like in the build script,
these misc documents are copied over to the isv plugin at build time.  If
we take the component approach, we could do something similar.  But
I think it would be more trouble than it's worth (especially considering
how our javadoc is built on WST/JST level).

Jeffrey Liu <jeffliu@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

07/06/2005 10:32 AM

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

To	"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc
Subject	Re: [wtp-dev] ISV documentation and API docs/Javadoc - ACTION REQUIRED

Hi Susan, 

My knowledge on docs are very limited, so bear with me... As background,
we are building the isv plugins as part of the WTP builds. Right now, these
isv plugins only contain javadocs. These javadocs are built on the WST
and JST level. So they are not broken up into the levels that you described
below (Web services, XML, etc...). To change this, we need to do some surgery
to the build process. IHMO, I think we need more discussion on this before
proceeding with breaking up the WST and JST javadocs into finer levels.
Does anyone know how Eclipse does their javadocs? 

Currently, there are two "books" in the Help system. They are
structured as follow: 

Java Standard Tools Developer Guide 
   Reference 
       API Reference 

Web Standard Tools Developer Guide 
   Reference 
       API Reference 

Basically, this is the structure that Eclipse uses. So instead of using
a sub-topic named "JavaDoc", I say we stick with the above topics
(just to be consistent with Eclipse). 

Thanks, 

Jeff

Susan Yeshin/Toronto/IBM@IBMCA
Sent by: wtp-dev-bounces@xxxxxxxxxxx

07/06/2005 09:58 AM

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

To	wtp-dev@xxxxxxxxxxx
cc
Subject	[wtp-dev] ISV documentation and API docs/Javadoc - ACTION REQUIRED

The general structure for the ISV documentation will be as follows:

There should be two 'books' for the ISV guide, one for wst and one for
jst. Inside each book will be anchors to the isv doc plugin and javadoc
for each component. 

WST Developer Guide
Extending Web services
  Programmer's guide
  JavaDoc
Extending XML tools
  Programmer's guide
  JavaDoc 

In this example there would have the following plugins 

org.eclipse.wst.doc.isv - will contain the master navigation (I will handle
this) 
   org.eclipse.wst.webservices.doc.isv 
              tocfile.xml
      plugin.xml 
      topics 
           extendwsoverview.html
           extendwspt1.html
                   extendwspt2.html
              images
                    screencap.gif
(use only if needed and please grab the smallest part of the screen you
can) 
  toc link to - org.eclipse.wst.webservices.javadoc***?? - need to
find out what plugins the developers put their javadoc in.
   org.eclipse.wst.xml.doc.isv 
              tocfile.xml
      plugin.xml 
      topics 
           extendxmloverview.html
           extendxmlpt1.html
                   extendxmlpt2.html
              images
 toc link to -  org.eclipse.wst.xml.javadoc***??

The same structure would be used for each component under wst and under
jst projects.

Please send a note with the extension points you would like covered in
your component's guide and send the plugin name that contains your API
docs (I do hope they are in a separate plugin) to christoph and cc me.
Christoph will be documenting the ISV guides and will likely be contacting
you for information.  Please also open a Bugzilla bug with this same
information and add the bug # to the email sent. 

Christoph's email - ckrawczyk@xxxxxxxxxxxxx
I will be away for a week and will only be able to read my Yahoo mail -
syeshin@xxxxxxxxx 


Thanks, 
Susan Yeshin

Rational Tools Information Development
IBM Toronto Lab
D3 - 446
syeshin@xxxxxxxxxx
(905) 413-3662
t/l 8-969-3662
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev