headers
Stephane Bortzmeyer | 2 Jun 2005 16:22
Picon

Documenting a XML-RPC API with Docbook?

[Sorry for the cross-posting but it is really an issue for both
lists.]

I'm currently documenting the API of a XML-RPC
(http://www.xmlrpc.com/) server in Docbok and I wonder if there is One
True Way to do it?

Docbook markup for functions seems quite C-oriented and I was thinking
about the best mapping.

For instance, if I have a XML-RPC procedure defined as:

string domain.delete(name string, credentials struct)

I currently use:

<funcsynopsis>
  <funcprototype>
    <funcdef>string
    <function>domain.delete</function></funcdef>
    <paramdef><parameter>name</parameter> string</paramdef>
    <paramdef><parameter>credentials</parameter> string</paramdef>
  </funcprototype>
</funcsynopsis>

Does it seem correct? (Let's not talk about the rendering yet, I'll
ask on docbook-apps.)

 
Yahoo! Groups Links
(Continue reading)

Permalink | Reply | 0 comments |
headers
Paul Libbrecht | 2 Jun 2005 16:49

Re: Documenting a XML-RPC API with Docbook?

I'll speak from the XML-RPC side, if I dare.
Such an encoding would be really welcome, after many searches I know 
none, even for SOAP or OWL-S (where WSDL seems just not for humans).

In your example, I see no definition of "recursive types", e.g. using 
records or lists with documentation on the type of contained objects.
Is it planned ?

the encoding that I can read there:
             return-type <function>funcName</function>
and 	     <parameter> paramName </parameter> param-type

sounds a bit weird to me. Is this the holy way in DocBook ?

thanks

paul

Le 2 juin 05, à 16:22, Stephane Bortzmeyer a écrit :

> [Sorry for the cross-posting but it is really an issue for both
> lists.]
>
> I'm currently documenting the API of a XML-RPC
> (http://www.xmlrpc.com/) server in Docbok and I wonder if there is One
> True Way to do it?
>
> Docbook markup for functions seems quite C-oriented and I was thinking
> about the best mapping.
>
(Continue reading)

Permalink | Reply | 0 comments |
headers
Stephane Bortzmeyer | 2 Jun 2005 16:51
Picon

Re: Documenting a XML-RPC API with Docbook?

On Thu, Jun 02, 2005 at 04:49:50PM +0200,
 Paul Libbrecht <paul <at> activemath.org> wrote 
 a message of 66 lines which said:

> In your example, I see no definition of "recursive types", e.g. using 
> records or lists with documentation on the type of contained objects.
> Is it planned ?

Yes, it would be a good idea, I'll try.

> the encoding that I can read there:
>              return-type <function>funcName</function>
> and 	     <parameter> paramName </parameter> param-type
> 
> sounds a bit weird to me. Is this the holy way in DocBook ?

I'm afraid so.

 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/xml-rpc/

<*> To unsubscribe from this group, send an email to:
    xml-rpc-unsubscribe <at> yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/
(Continue reading)

Permalink | Reply | 0 comments |
headers
bryanh | 2 Jun 2005 17:15

Re: Re: Documenting a XML-RPC API with Docbook?

For those of us, like me, who are not terribly familiar with Docbook,
let me clarify what you're doing.  Correct me if I'm wrong.

Docbook defines some element types for documenting the API of a
program function.  These types may be intended for program functions
in general, but in practice they're designed around C and are useful
in other languages only to the extent that the language is similar to
C.

You're looking for a convention for applying those (or any other
existing Docbook element types) to an XML-RPC interface.

--

-- 
Bryan Henderson                                    Phone 408-621-2000
San Jose, California

 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/xml-rpc/

<*> To unsubscribe from this group, send an email to:
    xml-rpc-unsubscribe <at> yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/
Permalink | Reply | 0 comments |
headers
Stephane Bortzmeyer | 2 Jun 2005 17:22
Picon

Re: Documenting a XML-RPC API with Docbook?

On Thu, Jun 02, 2005 at 03:15:08PM +0000,
 bryanh <at> giraffe-data.com <bryanh <at> giraffe-data.com> wrote 
 a message of 31 lines which said:

> Docbook defines some element types for documenting the API of a
> program function.  These types may be intended for program functions
> in general, but in practice they're designed around C and are useful
> in other languages only to the extent that the language is similar
> to C.
> 
> You're looking for a convention for applying those (or any other
> existing Docbook element types) to an XML-RPC interface.

Excellent summary.

 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/xml-rpc/

<*> To unsubscribe from this group, send an email to:
    xml-rpc-unsubscribe <at> yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/
Permalink | Reply | 0 comments |
headers
Gaetano Giunta | 3 Jun 2005 12:51
Picon

RE: Documenting a XML-RPC API with Docbook?

As a side note: the only "standard" way to describe exposed xmlrpc functions (AFAIK) is the
system.listmethods family (described here
http://scripts.incutio.com/xmlrpc/introspection.html), which unfortunately allows no recursive
info. This makes it pretty useless in the end, whreas WSDL really has taken off.

Maybe a push in that direction could bring some results?

> -----Original Message-----
> From: xml-rpc <at> yahoogroups.com 
> [mailto:xml-rpc <at> yahoogroups.com]On Behalf
> Of Paul Libbrecht
> Sent: Thursday, June 02, 2005 4:50 PM
> To: xml-rpc <at> yahoogroups.com
> Cc: docbook <at> lists.oasis-open.org
> Subject: Re: [xml-rpc] Documenting a XML-RPC API with Docbook?
> 
> 
> I'll speak from the XML-RPC side, if I dare.
> Such an encoding would be really welcome, after many searches I know 
> none, even for SOAP or OWL-S (where WSDL seems just not for humans).
> 
> In your example, I see no definition of "recursive types", e.g. using 
> records or lists with documentation on the type of contained objects.
> Is it planned ?
> 
> the encoding that I can read there:
>              return-type <function>funcName</function>
> and 	     <parameter> paramName </parameter> param-type
> 
> sounds a bit weird to me. Is this the holy way in DocBook ?
(Continue reading)

Permalink | Reply | 3 comments |
headers
Paul Libbrecht | 3 Jun 2005 13:09

Re: Documenting a XML-RPC API with Docbook?

Do I mistake or WSDL allows only machine readable information which, of 
course, can be rendered, but is rarely decorated with human comments.
I'm looking for something at least as powerful javadoc.

paul

Le 3 juin 05, à 12:51, Gaetano Giunta a écrit :

> As a side note: the only "standard" way to describe exposed xmlrpc 
> functions (AFAIK) is the system.listmethods family (described here 
> http://scripts.incutio.com/xmlrpc/introspection.html), which 
> unfortunately allows no recursive info. This makes it pretty useless 
> in the end, whreas WSDL really has taken off.
>
> Maybe a push in that direction could bring some results?
>
>> -----Original Message-----
>> From: xml-rpc <at> yahoogroups.com
>> [mailto:xml-rpc <at> yahoogroups.com]On Behalf
>> Of Paul Libbrecht
>> Sent: Thursday, June 02, 2005 4:50 PM
>> To: xml-rpc <at> yahoogroups.com
>> Cc: docbook <at> lists.oasis-open.org
>> Subject: Re: [xml-rpc] Documenting a XML-RPC API with Docbook?
>>
>>
>> I'll speak from the XML-RPC side, if I dare.
>> Such an encoding would be really welcome, after many searches I know
>> none, even for SOAP or OWL-S (where WSDL seems just not for humans).
>>
(Continue reading)

Permalink | Reply | 2 comments |
headers
Gaetano Giunta | 3 Jun 2005 14:11
Picon

RE: Documenting a XML-RPC API with Docbook?

Wsdl has more expressive power than xmlrpc introspection.

As far as human-readable information is concerned, there is nothing stopping the users from agreeing upon
structured comments to wsdl files and building parsers that will output nicely formatted documentation.

Of course the same can be done for xmlrpc. It is, imho, just a matter of having lib implementors to agree on a spec.

How about a javadoc-extension to system.methodHelp? e.g system.methodJDoc will return a complete
javadoc 'block' (sans initial and end comment tags) that the caller is free to parse and render as
html/pdf/whatever. Usual Javadoc syntax applies.

Depending on introspection capabilities of the chosen language, lib builders could even create
stub-generators that expose native functions as xmlrpc functions and make available the javadoc found
in source code to xmlrpc callers...

bye
Gaetano

> -----Original Message-----
> From: xml-rpc <at> yahoogroups.com 
> [mailto:xml-rpc <at> yahoogroups.com]On Behalf
> Of Paul Libbrecht
> Sent: Friday, June 03, 2005 1:09 PM
> To: xml-rpc <at> yahoogroups.com
> Subject: Re: [xml-rpc] Documenting a XML-RPC API with Docbook?
> 
> 
> Do I mistake or WSDL allows only machine readable information 
> which, of 
> course, can be rendered, but is rarely decorated with human comments.
(Continue reading)

Permalink | Reply | 1 comment |
headers
Paul Libbrecht | 3 Jun 2005 14:55

Re: Documenting a XML-RPC API with Docbook?


Le 3 juin 05, à 14:11, Gaetano Giunta a écrit :
> [.. ]As far as human-readable information is concerned, there is 
> nothing stopping the users from agreeing upon structured comments to 
> wsdl files and building parsers that will output nicely formatted 
> documentation.
>
> Of course the same can be done for xmlrpc. It is, imho, just a matter 
> of having lib implementors to agree on a spec.

As usual.

> How about a javadoc-extension to system.methodHelp? e.g 
> system.methodJDoc will return a complete javadoc 'block' (sans initial 
> and end comment tags) that the caller is free to parse and render as 
> html/pdf/whatever. Usual Javadoc syntax applies.
> Depending on introspection capabilities of the chosen language, lib 
> builders could even create stub-generators that expose native 
> functions as xmlrpc functions and make available the javadoc found in 
> source code to xmlrpc callers...

That might be doable on the top of XDoclet but is then based on the 
library taken which is not, necessarily the best choice.
I had hoped something like DocBook to bring in a bit of "standards 
oil"...

paul

 
Yahoo! Groups Links
(Continue reading)

Permalink | Reply | 0 comments |
headers
Sudhakar Anivella | 8 Jun 2005 20:44
Picon
Favicon

www.xmlrpc.com

Since two days I am unable to browse www.xmlrpc.com.
Sometimes browser says connection is refused and
sometimes it says no data in response.

regards
Sudhakar

		
__________________________________________________________
How much free photo storage do you get? Store your friends 'n family snaps for FREE with Yahoo! Photos http://in.photos.yahoo.com

 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/xml-rpc/

<*> To unsubscribe from this group, send an email to:
    xml-rpc-unsubscribe <at> yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/
Permalink | Reply | 2 comments |

Gmane