Strawman argument type definition language

Ivan R. Judson judson at mcs.anl.gov
Tue Jul 29 23:33:52 CDT 2003


I'm not sure I can see the value of more effort on our part to build a
documentation system, we can just use the existing structured text
mechanisms (http://www.python.org/sigs/doc-sig/stext.html) and happydoc
and/or pydoc will create reasonable html (and other formats) documentation.
The problem of what is the SOAP interface should get more clear when we have
Interface objects more explicitly represented in our software...

I'd vote for us just writing a programmers style guide and including a
section on how to document the code so that it's clear for others to read.

The other point, I think, is that we don't need python independent
documentation yet, since we don't have interoperability. When we write the
schemas (which also themselves have documentation mechanisms) we will have
documented the data types in a language independent fashion. But until then
it's a waste of effort, since developers have to use python until we get
SOAP interop working anyhow...

--Ivan

> -----Original Message-----
> From: owner-ag-dev at mcs.anl.gov 
> [mailto:owner-ag-dev at mcs.anl.gov] On Behalf Of Robert Olson
> Sent: Monday, July 28, 2003 5:15 PM
> To: ag-dev at mcs.anl.gov
> Subject: Strawman argument type definition language
> 
> 
> What if we could add the following declaration to a class 
> that exports SOAP 
> methods:
> 
>      soap_types = """
> 
>          struct Capability {
>              string role;
>              string type;
>              dict parms;
>              };
> 
>    	typedef string URIType;
>         typedef base64 IconType;
> 
>      	struct clientProfile {
>              string techSupportInformation;
>              string profileType;
>              string geoLocation;
>              string email;
>              string name;
>              string phoneNumber;
>              IconType icon;
>              URIType uri;
>              string publicId;
>              string distinguishedName;
>              Capability[] capabilities;
>              };
> 	struct EnterReturn {
> 	     VenueState state;
> 	     string privateId;
> 	     StreamDescription[] streams;
> 	};
>              """
> 
> And then, when we export a method, we say
> 
>      wsEnter.soap_export_as = "Enter"
>      wsEnter.soap_argument_types = ["clientProfile"]
>      wsEnter.soap_return_type = "EnterReturn"
> 
> This pretty much finishes the picture as far as completely 
> defining what 
> SOAP methods are, what their arguments are, and what they 
> return. This 
> syntax is easily parsable, can be used to auto-generate 
> documentation, and 
> could be used in the future to generate WSDL or schema defs, or 
> interface/impl stub code.
> 
> --bob
> 




More information about the ag-dev mailing list