Marcel,
After thinking a bit more about your proposal and combining your ideas
with findings I made some time ago when thinking about best practices
to add documentation to WSDL/XSDs, I would like to make the following
comments:
1. In its present form, your proposal neglects a fundamental
constraint, namely that wsdl2java is used in contract first scenarios
where in many cases the WSDL/XSD is submitted to other teams and/or
organizations that don't necessarily use the same tools. It is
therefore important to avoid introducing syntax specific to a single
tool, because this would make the documentation useless when the
WSDL/XSD is processed by another team/organization, or within the same
team/organization, but with a different tool. E.g. the documentation
in xs:annotation/xs:appinfo/dc:description will (probably) not be
visible when opening the schema with XMLSpy, which is a popular tool
used in many organizations. The only way to satisfy this portability
requirement is to use xs:annotation/xs:documentation elements with
plain text content [1]. That is of course a very strict constraint.
2. The limited reaction by the community to your proposal is probably
an indication of some lack of interest. Probably one could generate
more interest by somewhat enlarging the scope of the proposal, namely
by including wsimport and by adding a tool that generates human
readable (browsable or printable) documentation directly from
WSDL/XSDs. Including wsimport may generate interest outside of the
Axis2 project as can be seen in [2] and [3]. A good documentation
generator could generate interest because there are not that many good
open source tools available.
3. There are some additional challenges when generating Javadoc from
WSDL/XSDs that are not addressed by existing solutions:
a. Since the content of xs:documentation is plain text, any formatting
(paragraphs, lists, etc.) is lost. As an example, you may consider the
code generated from [4] by wsimport.
b. The names of the Java classes and properties are not necessarily
the same as the names of the corresponding types and elements in the
schema. This in particular occurs with wsimport when using JAXB
customizations. E.g. I'm working in project where the guideline is to
use names ending with "Type" for all XSD types. Since having class
names ending with "Type" looks very silly in Java, I usually customize
the JAXB bindings to strip the "Type" suffix from these names. This is
a problem if the XSD documentation contains cross-references to other
types or elements, because the generated Javadoc will not be in sync
with the generated code. This is of course due to the fact that
current code generators cannot extract any semantic information from
the (plain text) xs:documentation element.
c. For the same reasons as item b., no {...@link} annotations will be
generated. This makes it difficult to navigate the generated Javadoc.
An interesting project would be to propose a consistent solution for
these issues. This necessarily requires the definition of some form of
semantic annotation for the WSDL/XSD documentation (so that e.g. the
code generator can identify cross-references and replace them by the
right Java names). At first glance this seems to be in contradiction
with point 1 because one immediately things about XML markup to
achieve this. However, an alternative would be to define some sort of
Wiki-style syntax that leaves the xs:documentation element as plain
text, is human readable, interacts well with existing tools and that
at the same time has enough semantics to enable generation of high
quality Javadoc.
Regards,
Andreas
[1] If I remember well, the specs don't say anything about markup in
xs:documentation. Some time ago I checked how different tools react to
(HTML) markup in xs:documentation, and most of them render it
verbatim. E.g. wsimport will escape any angle brackets and ampersands
before inserting the documentation into the Javadoc.
[2] https://jaxb.dev.java.net/issues/show_bug.cgi?id=172
[3] http://www.mail-archive.com/[email protected]/msg02796.html
[4] http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd
On Thu, Apr 8, 2010 at 23:36, Heusinger, Marcel
<[email protected]> wrote:
>>Two quick questions about your proposal:
>>
>>- Axis2 supports several binding styles. There is the classic code
>>generator (wsdl2java) that supports different data bindings (the
>>default ADB, xmlbeans, JIBX,...), but there is also support for JAX-WS
>>artifacts generated by wsimport (which is not part of Axis2, but that
>>comes from Sun's JAX-WS reference implementation). What would be the
>>scope of this project?
>>- Can you give an example of how an annotated XML schema element would
>>look like? That would give us a better understanding of the ideas you
>>have in mind.
>>
>>Thanks.
>>
>>Andreas
>
> First of all thanks for your reply. To answer your first question, I had
> the idea while generating proxies with java2wsdl using its default
> binding adb. As I haven't tried out the other bindings yet, I would
> limit to this combination for the moment. Althought I haven't worked out
> every detail of the mapping, I have something on my mind like the
> following:
>
> <description xmlns="http://www.w3.org/ns/wsdl";
> xmlns:dc="http://purl.org/dc/terms/"; ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/";>
> <dc:description>This parameter represents
> ...</dc:description>
> </xs:appinfo>
> </xs:annotation>
> </xs:element>
>
> <xs:element name="response" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/";>
> <dc:description>This will be returned ...</dc:description>
> </xs:appinfo>
> </xs:annotation>
> </xs:element>
>
> <xs:element name="simpleError" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/";>
> <dc:description>Thrown if ...</dc:description>
> </xs:appinfo>
> </xs:annotation>
> </xs:element>
> </xs:schema>
> </types>
>
> <interface name="webServiceInterface" >
>
> <fault name="simpleFault"
> element="simpleError" />
>
> <operation
> name="SimpleOperation"
> pattern="http://www.w3.org/ns/wsdl/in-out";
> style="http://www.3w.org/ns/wsdl/style/iri";
> wsdlx:safe="true">
>
> <input
> messageLabel="In"
> element="request" />
>
> <out
> messageLabel="Out"
> element="response" />
>
> <outfault
> ref="simpleFault"
> messageLabel="Out" />
>
> <documentation>
> <dc:description>This is the method's description ...
> </dc:description>
> <dc:creator>Developer</dc:creator>
> <dc:relation>AnotherOperation</dc:relation>
> </ documentation >
> </operation>
>
> <operation
> name="AnotherOperation"
> pattern="http://www.w3.org/ns/wsdl/in-out"; ...
>
> ...
> </description>
>
>
> The proxy's method should be annotated like the following:
>
> /**
> * This is the method's description ...
> * @param request This parameter represents ...
> * @return This will be returned ...
> * @see AnotherOperation
> * @throws SimpleFault Thrown if ...
> * @author Developer
> public Response SimpleOperation (Request ...
> ...
> }
>
> Hope that I could explain what I intended with my proposal by providing
> this simplified example, which has to be worked out in more detail of
> course.
> Thanks.
> Marcel
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [email protected]
> For additional commands, e-mail: [email protected]
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
