WSDL best practices?

[Keith Hatton <kh...@axiomsystems.com>]

Hi all,

I'm looking for any experiences and thoughts about best use of the <documentation> tag in WSDL.

In particular, I've noticed that if I use it in the <porttype> section of my WSDL, the text is copied as a comment into the interface Java source code, which is nice (though it would be even better if the comment was Javadoc-style rather than // ...). But <documentation> elements in the <types> section seem to be ignored in the generated Java files.

What sections are worth putting <documentation> into? I'm thinking particularly for the benefit of code-generation tools (including but not limited to Axis).

Thanks
Keith

Re: WSDL best practices?

[Tom Oinn <tm...@ebi.ac.uk>]

Hi Keith,

I'd suggest that you document everything, whether used by current tools 
or not. The project I'm involved with is based on consuming web services 
and other resources and compositing them into workflows, any additional 
information we can gather from the WSDL to guide the users through this 
process is valuable - if we can find documentation for an operation and 
the parameters it takes it is much easier for our workflow designer to 
determine whether the service is appropriate.

Cheers,

Tom Oinn (taverna.sf.net)