Re: documentation generated from .wsdl

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: 4169395063@fido.ca



"Michael Potter" <pottmi@gmail.com> 
Sent by: www-ws-desc-request@w3.org
08/09/2007 03:04 PM

To
www-ws-desc@w3.org
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