+1 .. I think the main issue with docs is getting people to do it. While Dublin Core has been around for a long time adoption in the Web services / SOA worlds is minimal/non-existent. As such a tool that depends on those annotations being present will likely see little use.
Marcel, I don't want to blunt your enthusiasm for participating in Axis2. Do you have other ideas or variations that interest you? Do you want ideas on things you can do? Sanjiva. On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen <[email protected]>wrote: > 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] > > -- Sanjiva Weerawarana, Ph.D. Founder, Director & Chief Scientist; Lanka Software Foundation; http://www.opensource.lk/ Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/ Member; Apache Software Foundation; http://www.apache.org/ Director; Sahana Software Foundation; http://www.sahanafoundation.org/ Visiting Lecturer; University of Moratuwa; http://www.cse.mrt.ac.lk/ Blog: http://sanjiva.weerawarana.org/
