RE: proposal for improving <documentation>

I don't have a problem with allowing UML models in the <documentation>
element.  Documentation spanning the continuum from text, through xhtml
and svg to uml seems perfectly fine to me.  If you don't consider UML as
human readable, you could put it as a sibling to <documentation> instead
of within it.

> -----Original Message-----
> From: Sanjiva Weerawarana [mailto:sanjiva@watson.ibm.com]
> Sent: Friday, September 19, 2003 2:38 AM
> To: Jonathan Marsh; www-ws-desc@w3.org
> Subject: Re: proposal for improving <documentation>
> 
> Hi Jonathan,
> 
> > [Speaking personally. I just can't keep quiet on this one!]
> >
> > XSD has xsd:annotation/xsd:appInfo because they don't allow
extension
> > elements in arbitrary spots.  We do, so we can add machine-readable
> > information anywhere in WSDL.
> 
> Good point. However, what I was looking for was a way to distinguish
> between arbitrary extensions that are intended for "regular"
> processing by the processor vs. "hints" or "documentation" kind of
> hints which are intended as additional information for some processor
> which cares, but nothing that would break the understanding of the
> full WSDL.
> 
> Yes you could argue there proper use of wsdl:required is the way
> to separate the two, but I think there's a subtle difference
> between "documentation" kind of extensions and other extensions.
> 
> > The extra complexity in the syntax is
> > therefore completely unnecessary, and not backward compatible with
WSDL
> > 1.1.  I have always thought Schema's extensibility model was
needlessly
> > Byzantine and hope we won't make the same mistake.
> 
> :-)
> 
> OK so given this valuable experience, how about if we loosen the
> wording on <documentation> to not insist that its intended for
> human consumption? The XSD type is currently mixed, which is fine
> as it allows both human consumable stuff as well as machine
> processable stuff. If we relax the wording a bit to say that
> that's to be used for documentation purposes, whether for human
> or machine consumption (and hence we have mixed content) that would
> be ok I think.
> 
> I'm by no means looking for ways to make this beast more complex
> than needed. The problem that motivated this was to have an
> architected way to associate a UML model with a WSDL document,
> for example. Documentation is the right "level" of association
> as it is indeed documentation meant for humans or tools driven
> by humans .. hence my original note. So if we loosen the wording
> one could do something like this:
> 
>     <operation ...>
>         ...
>         <documentation>
>             <xxx:uml-model location="..."/>
>         </documentation>
>     </operation>
> 
> Sanjiva.
>

Received on Tuesday, 30 September 2003 20:38:47 UTC