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 Friday, 19 September 2003 05:39:00 UTC