Re: documentation generated from .wsdl

This is a multipart message in MIME format.
--=_alternative 004BBFF885257333_=
Content-Type: text/plain; charset="US-ASCII"

Mike,

Yes, wsdldoc processors exist. They produce documentation similar to 
javadoc. The approach is to use the <documentation> tags that are part of 
the wsdl markup.

I work at IBM and know of support for generating documentation in our tool 
products like Rational Application Developer. Craig and Keith can tell you 
about that. The tools also generate xsddoc for any schemas referenced from 
the wsdl. I believe some diagrams are also generated in the current 
version.

There is no standard for this, but since both wsdl and xsd are xml, you 
should easily be able to use xslt and fop to generate simple html and pdf 
documentation.

Arthur Ryman, PhD, AoT, DE
Process and Portfolio Management, Rational Division

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-3831 (T/L: 318-8867)
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: [email protected]



"Michael Potter" <[email protected]> 
Sent by: [email protected]
08/09/2007 03:04 PM

To
[email protected]
cc

Subject
documentation generated from .wsdl







wsdl list,

I have a need to document our webservices in a format usable by
non-technical users.

What I have in mind is some additional markup in my .wsdl files that I
will filter and use to generate .pdf/.html files.  This would be done in 
the
spirit of javadoc for java and pod for perl.

My questions are:
1) Has anyone already done such a thing?
2) Is there a standard way to do that?

I am guessing that such a tool would use the
<xs:annotation>
<xs:documentation xml:lang="en">
<wsdl:documentation>
tags.

To be useful the tool would need to do more than just read those tags.
 Much like javadoc requires the comments in java to have a particular
format, the tool would have to have the mentioned tags to have a
specific format.

I apologize if this is not the correct forum for such a question.  If
you could point me to a proper forum I would appreciate it.

The context of this question is that I have 1200 webservices and would
like to produce documentation that is suitable for a sales situation.
I would like to maintain that documentation in the .wsdl file or other
source code so that it would stay up-to-date.

--
Michael Potter




--=_alternative 004BBFF885257333_=
Content-Type: text/html; charset="US-ASCII"


<br><font size=2 face="sans-serif">Mike,</font>
<br>
<br><font size=2 face="sans-serif">Yes, wsdldoc processors exist. They
produce documentation similar to javadoc. The approach is to use the &lt;documentation&gt;
tags that are part of the wsdl markup.</font>
<br>
<br><font size=2 face="sans-serif">I work at IBM and know of support for
generating documentation in our tool products like Rational Application
Developer. Craig and Keith can tell you about that. The tools also generate
xsddoc for any schemas referenced from the wsdl. I believe some diagrams
are also generated in the current version.</font>
<br>
<br><font size=2 face="sans-serif">There is no standard for this, but since
both wsdl and xsd are xml, you should easily be able to use xslt and fop
to generate simple html and pdf documentation.</font>
<br>
<br><font size=2 face="sans-serif">Arthur Ryman, PhD, AoT, DE<br>
Process and Portfolio Management, Rational Division<br>
<br>
phone: +1-905-413-3077, TL 969-3077<br>
assistant: +1-905-413-3831 (T/L: 318-8867)<br>
fax: +1-905-413-4920, TL 969-4920<br>
mobile: +1-416-939-5063, text: [email protected]</font>
<br>
<br>
<br>
<table width=100%>
<tr valign=top>
<td width=40%><font size=1 face="sans-serif"><b>&quot;Michael Potter&quot;
&lt;[email protected]&gt;</b> </font>
<br><font size=1 face="sans-serif">Sent by: [email protected]</font>
<p><font size=1 face="sans-serif">08/09/2007 03:04 PM</font>
<td width=59%>
<table width=100%>
<tr valign=top>
<td>
<div align=right><font size=1 face="sans-serif">To</font></div>
<td><font size=1 face="sans-serif">[email protected]</font>
<tr valign=top>
<td>
<div align=right><font size=1 face="sans-serif">cc</font></div>
<td>
<tr valign=top>
<td>
<div align=right><font size=1 face="sans-serif">Subject</font></div>
<td><font size=1 face="sans-serif">documentation generated from .wsdl</font></table>
<br>
<table>
<tr valign=top>
<td>
<td></table>
<br></table>
<br>
<br>
<br><tt><font size=2><br>
wsdl list,<br>
<br>
I have a need to document our webservices in a format usable by<br>
non-technical users.<br>
<br>
What I have in mind is some additional markup in my .wsdl files that I<br>
will filter and use to generate .pdf/.html files. &nbsp;This would be done
in the<br>
spirit of javadoc for java and pod for perl.<br>
<br>
My questions are:<br>
1) Has anyone already done such a thing?<br>
2) Is there a standard way to do that?<br>
<br>
I am guessing that such a tool would use the<br>
&lt;xs:annotation&gt;<br>
&lt;xs:documentation xml:lang=&quot;en&quot;&gt;<br>
&lt;wsdl:documentation&gt;<br>
tags.<br>
<br>
To be useful the tool would need to do more than just read those tags.<br>
 Much like javadoc requires the comments in java to have a particular<br>
format, the tool would have to have the mentioned tags to have a<br>
specific format.<br>
<br>
I apologize if this is not the correct forum for such a question. &nbsp;If<br>
you could point me to a proper forum I would appreciate it.<br>
<br>
The context of this question is that I have 1200 webservices and would<br>
like to produce documentation that is suitable for a sales situation.<br>
I would like to maintain that documentation in the .wsdl file or other<br>
source code so that it would stay up-to-date.<br>
<br>
--<br>
Michael Potter<br>
<br>
<br>
</font></tt>
<br>
--=_alternative 004BBFF885257333_=--