axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "keith chapman" <keithgchap...@gmail.com>
Subject Re: [Axis2] Proposal to chage the method signature of set/get documentation
Date Wed, 31 Oct 2007 05:17:49 GMT
Hi Tom,

Yes its not very common to have xml is tour documentation but there are
occations where such information can be helpful. Here is a sample wsdl which
has documentation as XML.

http://mashups.wso2.org/services/nationalgeographic?wsdl2&annotation=true If
you look at the source of it you will see how ugly the documentation looks.

Thanks,
Keith.

On 10/27/07, Tom Jordahl <tjordahl@adobe.com> wrote:
>
>  Removing String as an argument type seems like a bad idea to me for two
> reasons:
>
>
>
> 1. Breaking API compatibility, if it is public, is not nice.
>
>
>
> 2. If I want to put a string there (which I think you are saying goes in
> the <documentation> elements of the WSDL) you are making me create another
> object.  Sure it's "easy", but it doesn't make me like the API much.  I
> think putting a string in this element is the 90+% use case, right?  Who is
> putting XML in here?  Is there a public WSDL that you can point to that does
> this?
>
>
>
> --
> Tom Jordahl
>
>   ------------------------------
>
> *From:* keith chapman [mailto:keithgchapman@gmail.com]
> *Sent:* Friday, October 26, 2007 8:16 AM
> *To:* axis-dev@ws.apache.org
> *Subject:* Re: [Axis2] Proposal to chage the method signature of set/get
> documentation
>
>
>
> +1 for changing getDocumentation to return OMNode (no deprecation, same
> will have to go for setDocumentation). Although this is an API method its
> mostly used from within for generating the WSDL.
>
> Thanks,
> Keith.
>
> On 10/26/07, *Glen Daniels* <glen@thoughtcraft.com> wrote:
>
> Well, +1 except for the fact that you can't overload getDocumentation()
> and just change the return type - so there's no way to deprecate that
> one without adding another method like getDocumentationOM().  We could
> either do that and avoid breaking existing stuff, or just change
> getDocumentation() and accept the incompatible change.
>
> --Glen
>
> Sanjiva Weerawarana wrote:
> > +1.
> >
> > keith chapman wrote:
> >> Hi Devs,
> >>
> >> Currently the method signature for det/get documentation in
> >> AxisDescriptio is as follows.
> >>
> >>     public String getDocumentation();
> >>     public void setDocumentation(String documentation);
> >>
> >> As you can see it treats the documentation as a string. There are
> >> occasions where the documentation can be XML though. If the
> >> documentation is XML what we do currently is wrap it in CDATA tags.
> >> This works, but its not the best sollution.
> >>
> >> I propose deprecating the above methods and introducing the following
> >> methods which that documentation as an OMNode.
> >>
> >>     public OMNode getDocumentation();
> >>     public void setDocumentation(OMNode documentation);
> >>
> >> This will enable us to set the documentation as an OMText or OMElement.
> >>
> >> If needed we can retain the old methods without deprecating them (Just
> >> leave them as a convenience method), where they will call into the new
> >> method.
> >>
> >> The above proposal is targeted at improving the wsdl served by Axis2.
> >> With what we have currently documentation which is XML is wrapped in
> >> CDATA tags in the WSDL.
> >>
> >> Thanks,
> >> Keith.
> >>
> >> --
> >> Keith Chapman
> >> WSO2 Inc.
> >> Oxygen for Web Services Developers.
> >> http://wso2.org/
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: axis-dev-help@ws.apache.org
>
>
>
>
> --
> Keith Chapman
> WSO2 Inc.
> Oxygen for Web Services Developers.
> http://wso2.org/
>



-- 
Keith Chapman
WSO2 Inc.
Oxygen for Web Services Developers.
http://wso2.org/

Mime
View raw message