[Doc-SIG] Python Tutorial - urllib2

[Fredrik Lundh]

Martin Blais wrote:

> > javadoc's
> >
> >     {@link os.popen}
> >
> > is even shorter.
> >
> > hmm.  maybe a combination of rest/html/whatever and pythondoc markup
> > would be the ultimate tool for the library reference...
>
> <* heavy clapping sound of my footsteps while running away screaming in fear *>

really?  so what's so problematic with

    Converts a Python tuple or a Fault instance to an XML-RPC request.

    @def dumps(params, **options)
    @param params A tuple or {@link Fault} instance.
    @keyparam methodname If given, create a methodCall request for
        this method name.
    @keyparam methodresponse If given, create a methodResponse packet.
        If used with a tuple, the tuple must be a singleton (that is,
        it must contain exactly one element).
    @keyparam encoding The encoding to use for this request. Defaults to
        UTF-8.
    @return A string containing marshalled data.

compared to

    \begin{funcdesc}{dumps}{params\optional{, methodname\optional{,
                            methodresponse\optional{, encoding}}}}
    Convert \var{params} into an XML-RPC request.
    or into a response if \var{methodresponse} is true.
    \var{params} can be either a tuple of arguments or an instance of the
    \exception{Fault} exception class.  If \var{methodresponse} is true,
    only a single value can be returned, meaning that \var{params} must be of length 1.
    \var{encoding}, if supplied, is the encoding to use in the generated
    XML; the default is UTF-8.
    \end{funcdesc}

given that the former can be trivially converted to a well-defined information
model:

    <function name="xmlrpclib.dumps">
        <info>
            <name>dumps</name>
            <summary>Convert a Python tuple or a Fault instance to an
                XML-RPC request.</summary>
            <description>Convert a Python tuple or a Fault instance to an
                XML-RPC request.</description>
            <def>dumps(params, **options)</def>
            <param name="params">A tuple or Fault instance.</param>
            <keyparam name="methodname">If given, create a methodCall
                request for this method name.</keyparam>
            <keyparam name="methodresponse">If given, create a
                methodResponse packet. If used with a tuple, the tuple must
                be a singleton (that is, it must contain exactly one element).
                </keyparam>
            <keyparam name="encoding">The request encoding. Defaults to
                UTF-8.</keyparam>
            <return>A string containing marshalled data.</return>
        </info>
    </function>

for further processing, while the latter results in a nice

    <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
      <td><nobr><b><tt id='l2h-3717' xml:id='l2h-3717' class="function">dumps</tt></b>(</nobr></td>
      <td><var>params</var><big>[</big><var>, methodname</var><big>[</big><var>,
                     methodresponse</var><big>[</big><var>, encoding</var><var></var><big>]
        </big><var></var><big>]    </big><var></var><big>]</big><var></var>)
        </td></tr></table></dt>
    <dd>
    <P>
    Convert <var>params</var> into an XML-RPC request.
    or into a response if <var>methodresponse</var> is true.
    <var>params</var> can be either a tuple of arguments or an instance of the
    <tt class="exception">Fault</tt> exception class.  If <var>methodresponse</var> is true,
    only a single value can be returned, meaning that <var>params</var> must be of length 1.
    <var>encoding</var>, if supplied, is the encoding to use in the generated
    XML; the default is UTF-8.
    </dl>

tag soup.

</F>