Hey, I'm not sure if you are interested in this one:
I recently extended the code in java/src/internal for generating API documentation as DocBook XML [1] directly from the velocity comments in the code (like it is currently already done for generating HTML and JSP). DocBook XML can be used to create nearly every other existing output format, so we are using it to generate API documentation as a PDF document, see [2]. The first of the attached patches adds everything that's needed. I further discovered some occurrences of wrong usage of the velocity macros as well as some oddities that lead to non-validating results, see my second patch. This one you might even want to apply if you don't like the first patch. Best Regards, Johannes [1] http://www.docbook.org [2] http://www.suse.com/documentation/suse_manager/pdfdoc/book_susemanager_apidoc/book_susemanager_apidoc.pdf -- SUSE LINUX Products GmbH, HRB 16746 (AG Nürnberg) GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer
>From 00c004a31a7cc95a37d83f8ba5a79530a90b4fe6 Mon Sep 17 00:00:00 2001 From: Johannes Renner <[email protected]> Date: Fri, 9 Mar 2012 12:09:34 +0100 Subject: [PATCH 1/2] Add support for generating DocBook XML from the API documentation --- java/build.xml | 6 ++ java/buildconf/apidoc/docbook/api_index_ftr.txt | 11 +++ java/buildconf/apidoc/docbook/api_index_hdr.txt | 33 ++++++++ java/buildconf/apidoc/docbook/apiindex.txt | 5 + java/buildconf/apidoc/docbook/faqs.txt | 39 +++++++++ java/buildconf/apidoc/docbook/handler.txt | 69 ++++++++++++++++ java/buildconf/apidoc/docbook/macros.txt | 87 ++++++++++++++++++++ java/buildconf/apidoc/docbook/scripts.txt | 48 +++++++++++ .../com/redhat/rhn/internal/doclet/ApiDoclet.java | 15 +++- .../redhat/rhn/internal/doclet/DocBookDoclet.java | 38 +++++++++ .../redhat/rhn/internal/doclet/DocBookWriter.java | 75 +++++++++++++++++ 11 files changed, 424 insertions(+), 2 deletions(-) create mode 100644 java/buildconf/apidoc/docbook/api_index_ftr.txt create mode 100644 java/buildconf/apidoc/docbook/api_index_hdr.txt create mode 100644 java/buildconf/apidoc/docbook/apiindex.txt create mode 100644 java/buildconf/apidoc/docbook/faqs.txt create mode 100644 java/buildconf/apidoc/docbook/handler.txt create mode 100644 java/buildconf/apidoc/docbook/macros.txt create mode 100644 java/buildconf/apidoc/docbook/scripts.txt create mode 100644 java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookDoclet.java create mode 100644 java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookWriter.java diff --git a/java/build.xml b/java/build.xml index 0d74651..d29b7db 100644 --- a/java/build.xml +++ b/java/build.xml @@ -253,6 +253,12 @@ <antcall target="apidoc" /> </target> + <target name="apidoc-docbook" description="Generate docbook xml from the API"> + <property name="doclet.class" value="DocBookDoclet" /> + <property name="template.dir" value="docbook" /> + <antcall target="apidoc" /> + </target> + <target name="apidoc" description="Generate the api documentation" depends="init"> <path id="javadocpath"> <path refid="buildjars" /> diff --git a/java/buildconf/apidoc/docbook/api_index_ftr.txt b/java/buildconf/apidoc/docbook/api_index_ftr.txt new file mode 100644 index 0000000..7052f4d --- /dev/null +++ b/java/buildconf/apidoc/docbook/api_index_ftr.txt @@ -0,0 +1,11 @@ + <colophon> + <title>Colophon</title> + <para>This documentation is written in DocBook (see <ulink url="http://www.docbook.org"/>). The XML + source files were validated by <command>xmllint</command>, processed by <command>xsltproc</command>, + and converted into XSL-FO using a customized version of Norman Walsh's stylesheets. The final PDF is + formatted through XEP from RenderX. <phrase>The open source tools and the environment used to build + this manual are available in the package <systemitem class="resource">daps</systemitem>.</phrase> + The project's home page can be found at <ulink url="http://daps.sf.net/"/>. + </para> + </colophon> +</book> diff --git a/java/buildconf/apidoc/docbook/api_index_hdr.txt b/java/buildconf/apidoc/docbook/api_index_hdr.txt new file mode 100644 index 0000000..0d9033c --- /dev/null +++ b/java/buildconf/apidoc/docbook/api_index_hdr.txt @@ -0,0 +1,33 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd";> + +<book lang="en"> + <title>Spacewalk API Documentation</title> + <bookinfo> + <pubdate><?dbtimestamp?></pubdate> + <productname>Spacewalk</productname> + <productnumber>1.7</productnumber> + <bibliosource class="uri">https://fedorahosted.org/spacewalk</bibliosource> + <abstract> + <para> + Welcome to the Spacewalk API. By using the included API calls, you can easily automate many of + the tasks you perform everyday. All API calls are grouped by common functionality. + </para> + </abstract> + <legalnotice> + <title>Legal Notice</title> + <para>Copyright (c) 2012 Red Hat, Inc. + This software is licensed to you under the GNU General Public License, version 2 (GPLv2). There is + NO WARRANTY for this software, express or implied, including the implied warranties of MERCHANTABILITY + or FITNESS FOR A PARTICULAR PURPOSE. You should have received a copy of GPLv2 along with this software; + if not, see http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + </para> + <para> + Red Hat trademarks are not licensed under GPLv2. No permission is granted to use or replicate Red Hat + trademarks that are incorporated in this software or its documentation. + </para> + </legalnotice> + </bookinfo> + + <xi:include href="scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="faqs.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> diff --git a/java/buildconf/apidoc/docbook/apiindex.txt b/java/buildconf/apidoc/docbook/apiindex.txt new file mode 100644 index 0000000..fa22a56 --- /dev/null +++ b/java/buildconf/apidoc/docbook/apiindex.txt @@ -0,0 +1,5 @@ +#set ($path = "") +#set ($xml = ".xml") +#foreach ($handler in $handlers) + <xi:include href="$path$handler.className$xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> +#end diff --git a/java/buildconf/apidoc/docbook/faqs.txt b/java/buildconf/apidoc/docbook/faqs.txt new file mode 100644 index 0000000..443a173 --- /dev/null +++ b/java/buildconf/apidoc/docbook/faqs.txt @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd";> + +<preface> +<title>Frequently Asked Questions</title> + +<qandaset> + <qandaentry> + <question> + <para>What programming languages are supported by the Spacewalk API?</para> + </question> + <answer> + <para>Any language that provides an XMLRPC client interface will work with the Spacewalk API. While +Perl and Python are two of the most commonly used, an XMLRPC client implementation is available for every +common language.</para> + </answer> + </qandaentry> + <qandaentry> + <question> + <para>When trying to call a specific function, the error <quote>Fault returned from XML RPC Server, +fault code -1: Could not find method METHOD in class...</quote> is given. What is wrong?</para> + </question> + <answer> + <para>Typically this is seen when either a function name is being called that doesn't exist, the number +of parameters for a particular function is incorrect, or the type of a passed parameter is incorrect (Such as +an array is expected, but a String is passed). Check all of these things.</para> + </answer> + </qandaentry> + <qandaentry> + <question> + <para>Should I call an API method using the naming scheme <quote>methodName</quote> or +<quote>method_name</quote>?</para> + </question> + <answer> + <para>Both of these are valid names for the same method, so use whichever you prefer.</para> + </answer> + </qandaentry> +</qandaset> +</preface> diff --git a/java/buildconf/apidoc/docbook/handler.txt b/java/buildconf/apidoc/docbook/handler.txt new file mode 100644 index 0000000..cca7fea --- /dev/null +++ b/java/buildconf/apidoc/docbook/handler.txt @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd";> + +## One chapter per handler +<chapter role="namespace"> +<title>$handler.name</title> +<abstract><para>$handler.desc</para></abstract> + +#foreach ($call in $handler.calls) +<sect1> + <title><function>$call.name</function></title> + <para/> + + <variablelist> + ## The description of this call + <varlistentry> + <term>Description</term> + <listitem> + <para>$call.doc</para> + #if ($call.deprecated) + <para>Deprecated - $call.deprecatedReason</para> + #end + #if ($call.sinceAvailable) + <para>Available since: $call.sinceVersion</para> + #end + </listitem> + </varlistentry> + + ## The parameters + <varlistentry> + <term>Parameters</term> + <listitem> + <itemizedlist spacing="compact"> + #if ($call.params.size() <= 0) + <listitem><para>None</para></listitem> + #else + #foreach($param in $call.params) + #if ($param.trim().startsWith('<listitem>')) + $param + #else + <listitem><para>$param</para></listitem> + #end + #end + #end + </itemizedlist> + </listitem> + </varlistentry> + + ## The return value + <varlistentry> + <term>Return Value</term> + <listitem> + <itemizedlist spacing="compact"> + ## Find out if we need to put a <para> here + #if (!$call.returnDoc.trim().startsWith('<') && !$call.returnDoc.trim().startsWith('$')) + <listitem><para> + #end + $call.returnDoc + #if (!$call.returnDoc.trim().startsWith('<') && !$call.returnDoc.trim().startsWith('$')) + </para></listitem> + #end + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> +</sect1> +#end + +</chapter> diff --git a/java/buildconf/apidoc/docbook/macros.txt b/java/buildconf/apidoc/docbook/macros.txt new file mode 100644 index 0000000..c18c0ea --- /dev/null +++ b/java/buildconf/apidoc/docbook/macros.txt @@ -0,0 +1,87 @@ + +#set($date="dateTime.iso8601") + +#macro(serializer $serializer) +<listitem><para>$serializer</para></listitem> +#end +#macro(prop $type $value) +<listitem><para>$type "$value"</para></listitem> +#end +#macro(prop_desc $type $value $desc) +<listitem><para>$type "$value" - $desc</para></listitem> +#end +#macro(prop_array $key $type $desc) +<listitem> + <para>array "$key"</para> + <itemizedlist spacing="compact"> + <listitem><para>$type $desc</para></listitem> + </itemizedlist> +</listitem> +#end +#macro(prop_array_begin $key) +<listitem> + <para>array "$key"</para> + <itemizedlist spacing="compact"> +#end +#macro(prop_array_begin_desc $key $desc) +<listitem> + <para>array "$key" - $desc</para> + <itemizedlist spacing="compact"> +#end +#macro(prop_array_end) + </itemizedlist> +</listitem> +#end +#macro(struct $type) +<listitem> + <para>struct - $type</para> + <itemizedlist spacing="compact"> +#end +#macro(struct_end) + </itemizedlist> +</listitem> +#end +#macro(array) +<listitem> + <para>array:</para> + <itemizedlist spacing="compact"> +#end +#macro(array_end) + </itemizedlist> +</listitem> +#end +#macro(array_single $type $desc) +<listitem> + <para>array:</para> + <itemizedlist spacing="compact"> + <listitem><para>$type - $desc</para></listitem> + </itemizedlist> +</listitem> +#end +#macro(options) +<listitem override="none"> + <itemizedlist spacing="compact"> +#end +#macro(item $item) + <listitem><para>$item</para></listitem> +#end +#macro(item_desc $item, $desc) + <listitem><para>$item - $desc</para></listitem> +#end +#macro(options_end) + </itemizedlist> +</listitem> +#end +#macro(param $type $value) +<listitem><para>$type $value</para></listitem> +#end +#macro(param_desc $type $value $desc) +<listitem><para>$type $value - $desc</para></listitem> +#end +#macro(session_key) + #param("string", "sessionKey") +#end +#macro(return_int_success) +<listitem><para>int - 1 on success, exception thrown otherwise.</para></listitem> +#end + diff --git a/java/buildconf/apidoc/docbook/scripts.txt b/java/buildconf/apidoc/docbook/scripts.txt new file mode 100644 index 0000000..1e67fa9 --- /dev/null +++ b/java/buildconf/apidoc/docbook/scripts.txt @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd";> + +<preface> +<title>Sample Scripts</title> + +<example> + <title>Perl Example</title> + <para>This Perl example shows the <function>system.listUserSystems</function> call being used to get a +list of systems a user has access to. In the example below, the name of each system will be printed.</para> + <programlisting>#!/usr/bin/perl +use Frontier::Client; + +my $HOST = 'spacewalk.example.com'; +my $user = 'username'; +my $pass = 'password'; + +my $client = new Frontier::Client(url => "http://$HOST/rpc/api";); +my $session = $client->call('auth.login',$user, $pass); + +my $systems = $client->call('system.listUserSystems', $session); +foreach my $system (@$systems) { + print $system->{'name'}."\n"; +} +$client->call('auth.logout', $session);</programlisting> +</example> + +<example> + <title>Python Example</title> + <para>Below is an example of the <function>user.listUsers</function> call being used. Only the login of each +user is printed.</para> + <programlisting>#!/usr/bin/python +import xmlrpclib + +SPACEWALK_URL = "http://spacewalk.example.com/rpc/api"; +SPACEWALK_LOGIN = "username" +SPACEWALK_PASSWORD = "password" + +client = xmlrpclib.Server(SPACEWALK_URL, verbose=0) + +key = client.auth.login(SPACEWALK_LOGIN, SPACEWALK_PASSWORD) +list = client.user.list_users(key) +for user in list: + print user.get('login') + +client.auth.logout(key)</programlisting> +</example> +</preface> diff --git a/java/code/internal/src/com/redhat/rhn/internal/doclet/ApiDoclet.java b/java/code/internal/src/com/redhat/rhn/internal/doclet/ApiDoclet.java index 6c8027e..c1200cf 100644 --- a/java/code/internal/src/com/redhat/rhn/internal/doclet/ApiDoclet.java +++ b/java/code/internal/src/com/redhat/rhn/internal/doclet/ApiDoclet.java @@ -100,11 +100,19 @@ public class ApiDoclet { Tag methodDoc = getFirst(method.tags(XMLRPC_DOC)); if (methodDoc != null) { - call.setDoc(methodDoc.text()); + if (docType.equals("docbook")) { + call.setDoc(DocBookWriter.transcode(methodDoc.text())); + } else { + call.setDoc(methodDoc.text()); + } } for (Tag param : method.tags(XMLRPC_PARAM)) { - call.addParam(param.text()); + if (docType.equals("docbook")) { + call.addParam(DocBookWriter.transcode(param.text())); + } else { + call.addParam(param.text()); + } } if (method.tags(DEPRECATED).length > 0) { @@ -148,6 +156,9 @@ public class ApiDoclet { else if (docType.equals("singlepage")) { writer = new SinglePageWriter(); } + else if (docType.equals("docbook")) { + writer = new DocBookWriter(); + } else { writer = new JSPWriter(); } diff --git a/java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookDoclet.java b/java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookDoclet.java new file mode 100644 index 0000000..a5b0866 --- /dev/null +++ b/java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookDoclet.java @@ -0,0 +1,38 @@ +/** + * Copyright (c) 2012 Novell + * + * This software is licensed to you under the GNU General Public License, + * version 2 (GPLv2). There is NO WARRANTY for this software, express or + * implied, including the implied warranties of MERCHANTABILITY or FITNESS + * FOR A PARTICULAR PURPOSE. You should have received a copy of GPLv2 + * along with this software; if not, see + * http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + * + * Red Hat trademarks are not licensed under GPLv2. No permission is + * granted to use or replicate Red Hat trademarks that are incorporated + * in this software or its documentation. + */ + +package com.redhat.rhn.internal.doclet; + +import com.sun.javadoc.RootDoc; + +/** + * DocBookDoclet + * @version $Rev$ + */ +public class DocBookDoclet { + + private DocBookDoclet() { + } + + /** + * starts the {@link DocBookDoclet} + * @param root the doc root + * @return true if successful + * @throws Exception e + */ + public static boolean start(RootDoc root) throws Exception { + return ApiDoclet.start(root, "docbook"); + } +} diff --git a/java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookWriter.java b/java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookWriter.java new file mode 100644 index 0000000..31ec52d --- /dev/null +++ b/java/code/internal/src/com/redhat/rhn/internal/doclet/DocBookWriter.java @@ -0,0 +1,75 @@ +/** + * Copyright (c) 2012 Novell + * + * This software is licensed to you under the GNU General Public License, + * version 2 (GPLv2). There is NO WARRANTY for this software, express or + * implied, including the implied warranties of MERCHANTABILITY or FITNESS + * FOR A PARTICULAR PURPOSE. You should have received a copy of GPLv2 + * along with this software; if not, see + * http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + * + * Red Hat trademarks are not licensed under GPLv2. No permission is + * granted to use or replicate Red Hat trademarks that are incorporated + * in this software or its documentation. + */ + +package com.redhat.rhn.internal.doclet; + +import java.util.List; +import java.util.Map; + +/** + * DocBookWriter + * @version $Rev$ + */ +public class DocBookWriter extends DocWriter { + + private static final String DOCBOOK_OUTPUT = "./build/reports/apidocs/docbook/"; + private static final String DOCBOOK_TEMPLATES = "./buildconf/apidoc/docbook/"; + private static final String[] OTHER_FILES = {"faqs", "scripts"}; + + /** + * {@inheritDoc} + */ + public void write(List<Handler> handlers, + Map<String, String> serializers) throws Exception { + + // First macro-tize the serializer's docs + renderSerializers(DOCBOOK_TEMPLATES, serializers); + + // Lets do the index first + writeFile(DOCBOOK_OUTPUT + "book.xml", generateIndex(handlers, DOCBOOK_TEMPLATES)); + for (Handler handler : handlers) { + writeFile(DOCBOOK_OUTPUT + handler.getClassName() + ".xml", + generateHandler(handler, DOCBOOK_TEMPLATES)); + } + + for (String file : OTHER_FILES) { + writeFile(DOCBOOK_OUTPUT + file + ".xml", readFile(DOCBOOK_TEMPLATES + file + ".txt")); + } + } + + /** + * Transcode simple HTML markup into DocBook XML or remove if not relevant. + * + * @param string any string containing HTML markup + * @return string containing DocBook XML markup + */ + public static String transcode(String string) { + String ret = ""; + // Remove href, italic and br + ret = string.replaceAll("<a [^>]*>", ""); + ret = ret.replaceAll("</a>", ""); + ret = ret.replaceAll("<i>", ""); + ret = ret.replaceAll("</i>", ""); + ret = ret.replaceAll("<br/>", " "); + // Transform lists + ret = ret.replaceAll("<ul>", "</para><itemizedlist>"); + ret = ret.replaceAll("</ul>", "</itemizedlist><para>"); + ret = ret.replaceAll("<li>", "<listitem><para>"); + ret = ret.replaceAll("</li>", "</para></listitem>"); + // Remove arbitrary stuff + ret = ret.replaceAll("<Specified System>", "Specified System"); + return ret; + } +} -- 1.7.7
>From 54c4205279cca39f3c3a2d4c150f5a723f37e672 Mon Sep 17 00:00:00 2001 From: Johannes Renner <[email protected]> Date: Fri, 9 Mar 2012 14:37:21 +0100 Subject: [PATCH 2/2] Fix usage of velocity macros for API documentation --- .../xmlrpc/channel/org/ChannelOrgHandler.java | 2 +- .../rhn/frontend/xmlrpc/errata/ErrataHandler.java | 2 +- .../MultiOrgEntitlementsDtoSerializer.java | 2 +- .../rhn/frontend/xmlrpc/system/SystemHandler.java | 32 ++++++++++++-------- .../xmlrpc/system/config/ServerConfigHandler.java | 1 - .../system/custominfo/CustomInfoHandler.java | 6 ++- .../xmlrpc/systemgroup/ServerGroupHandler.java | 15 ++------- 7 files changed, 29 insertions(+), 31 deletions(-) diff --git a/java/code/src/com/redhat/rhn/frontend/xmlrpc/channel/org/ChannelOrgHandler.java b/java/code/src/com/redhat/rhn/frontend/xmlrpc/channel/org/ChannelOrgHandler.java index a5dcab2..b9221f1 100644 --- a/java/code/src/com/redhat/rhn/frontend/xmlrpc/channel/org/ChannelOrgHandler.java +++ b/java/code/src/com/redhat/rhn/frontend/xmlrpc/channel/org/ChannelOrgHandler.java @@ -62,7 +62,7 @@ public class ChannelOrgHandler extends BaseHandler { * @xmlrpc.param #session_key() * @xmlrpc.param #param_desc("string", "channelLabel", "label of the channel") * @xmlrpc.returntype - * #array("organizations") + * #array() * #struct("org") * #prop("int", "org_id") * #prop("string", "org_name") diff --git a/java/code/src/com/redhat/rhn/frontend/xmlrpc/errata/ErrataHandler.java b/java/code/src/com/redhat/rhn/frontend/xmlrpc/errata/ErrataHandler.java index e294d9e..6da34c3 100644 --- a/java/code/src/com/redhat/rhn/frontend/xmlrpc/errata/ErrataHandler.java +++ b/java/code/src/com/redhat/rhn/frontend/xmlrpc/errata/ErrataHandler.java @@ -593,7 +593,7 @@ public class ErrataHandler extends BaseHandler { * @xmlrpc.param #session_key() * @xmlrpc.returntype * #array() - * #struct() + * #struct("erratum") * #prop("int", "id") * #prop("int", "published") * #prop("string", "advisory") diff --git a/java/code/src/com/redhat/rhn/frontend/xmlrpc/serializer/MultiOrgEntitlementsDtoSerializer.java b/java/code/src/com/redhat/rhn/frontend/xmlrpc/serializer/MultiOrgEntitlementsDtoSerializer.java index 07359c8..9868f8b 100644 --- a/java/code/src/com/redhat/rhn/frontend/xmlrpc/serializer/MultiOrgEntitlementsDtoSerializer.java +++ b/java/code/src/com/redhat/rhn/frontend/xmlrpc/serializer/MultiOrgEntitlementsDtoSerializer.java @@ -39,7 +39,7 @@ import redstone.xmlrpc.XmlRpcSerializer; * #prop("int", "free_flex") * #prop("int", "used_flex") * #prop("int", "allocated_flex") - * #prop("int", "unallocated_flex") * + * #prop("int", "unallocated_flex") * #struct_end() */ public class MultiOrgEntitlementsDtoSerializer implements diff --git a/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/SystemHandler.java b/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/SystemHandler.java index ee41cca..be9ead2 100644 --- a/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/SystemHandler.java +++ b/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/SystemHandler.java @@ -1064,6 +1064,7 @@ public class SystemHandler extends BaseHandler { * #prop("string", "release") * #prop("string", "epoch") * #prop("string", "arch") + * #struct_end() * #array_end() * */ @@ -1491,7 +1492,8 @@ public class SystemHandler extends BaseHandler { * @xmlrpc.doc List the available groups for a given system. * @xmlrpc.param #param("string", "sessionKey") * @xmlrpc.param #param("int", "serverId") - * @xmlrpc.returntype array + * @xmlrpc.returntype + * #array() * #struct("system group") * #prop_desc("int", "id", "server group id") * #prop_desc("int", "subscribed", "1 if the given server is subscribed @@ -1499,6 +1501,7 @@ public class SystemHandler extends BaseHandler { * #prop_desc("string", "system_group_name", "Name of the server group") * #prop_desc("string", "sgid", "server group id (Deprecated)") * #struct_end() + * #array_end() */ public Object[] listGroups(String sessionKey, Integer sid) throws FaultException { // Get the logged in user and server @@ -1890,7 +1893,7 @@ public class SystemHandler extends BaseHandler { * filter the results to fetch the specific events they are looking for. * * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #param("int", "serverId") - ID of system. + * @xmlrpc.param #param_desc("int", "serverId", "ID of system.") * @xmlrpc.returntype * #array() * #struct("action") @@ -2145,7 +2148,7 @@ public class SystemHandler extends BaseHandler { * @xmlrpc.doc Provision a guest on the host specified. Defaults to: * memory=512MB, vcpu=1, storage=3GB. * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #param("int", "serverId") - ID of host to provision guest on. + * @xmlrpc.param #param_desc("int", "serverId", "ID of host to provision guest on.") * @xmlrpc.param #param("string", "guestName") * @xmlrpc.param #param_desc("string", "profileName", "Kickstart profile to use.") * @xmlrpc.returntype #return_int_success() @@ -2168,7 +2171,7 @@ public class SystemHandler extends BaseHandler { * * @xmlrpc.doc Provision a system using the specified kickstart profile. * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #param("int", "serverId") - ID of the system to be provisioned. + * @xmlrpc.param #param_desc("int", "serverId", "ID of the system to be provisioned.") * @xmlrpc.param #param_desc("string", "profileName", "Kickstart profile to use.") * @xmlrpc.returntype int - ID of the action scheduled, otherwise exception thrown * on error @@ -2220,7 +2223,7 @@ public class SystemHandler extends BaseHandler { * * @xmlrpc.doc Provision a system using the specified kickstart profile. * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #param("int", "serverId") - ID of the system to be provisioned. + * @xmlrpc.param #param_desc("int", "serverId", "ID of the system to be provisioned.") * @xmlrpc.param #param_desc("string", "profileName", "Kickstart profile to use.") * @xmlrpc.param #param("dateTime.iso8601", "earliestDate") * @xmlrpc.returntype int - ID of the action scheduled, otherwise exception thrown @@ -2280,7 +2283,7 @@ public class SystemHandler extends BaseHandler { * or if OSAD is enabled will begin immediately. * * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #param("int", "serverId") - ID of host to provision guest on. + * @xmlrpc.param #param_desc("int", "serverId", "ID of host to provision guest on.") * @xmlrpc.param #param("string", "guestName") * @xmlrpc.param #param_desc("string", "profileName", "Kickstart Profile to use.") * @xmlrpc.param #param_desc("int", "memoryMb", "Memory to allocate to the guest") @@ -3175,8 +3178,7 @@ public class SystemHandler extends BaseHandler { * * @xmlrpc.doc Schedule a script to run. * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #array_single("int", "systemIds") - IDs of the servers to run - * the script on. + * @xmlrpc.param #array_single("int", "System IDs of the servers to run the script on.") * @xmlrpc.param #param_desc("string", "username", "User to run script as.") * @xmlrpc.param #param_desc("string", "groupname", "Group to run script as.") * @xmlrpc.param #param_desc("int", "timeout", "Seconds to allow the script to run @@ -3241,7 +3243,7 @@ public class SystemHandler extends BaseHandler { * * @xmlrpc.doc Schedule a script to run. * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #param("int", "serverId") - ID of the server to run the script on. + * @xmlrpc.param #param_desc("int", "serverId", "ID of the server to run the script on.") * @xmlrpc.param #param_desc("string", "username", "User to run script as.") * @xmlrpc.param #param_desc("string", "groupname", "Group to run script as.") * @xmlrpc.param #param_desc("int", "timeout", "Seconds to allow the script to run @@ -3416,7 +3418,7 @@ public class SystemHandler extends BaseHandler { * @xmlrpc.doc Set server details. All arguments are optional and will only be modified * if included in the struct. * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.param #param("int", "serverId") - ID of server to lookup details for. + * @xmlrpc.param #param_desc("int", "serverId", "ID of server to lookup details for.") * @xmlrpc.param * #struct("server details") * #prop_desc("string", "profile_name", "System's profile name") @@ -4028,8 +4030,10 @@ public class SystemHandler extends BaseHandler { * @xmlrpc.doc Lists systems that have been inactive for the default period of * inactivity * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.returntype array - * $SystemOverviewSerializer + * @xmlrpc.returntype + * #array() + * $SystemOverviewSerializer + * #array_end() */ public List listInactiveSystems(String sessionKey) { User loggedInUser = getLoggedInUser(sessionKey); @@ -4048,8 +4052,10 @@ public class SystemHandler extends BaseHandler { * number of days.. * @xmlrpc.param #param("string", "sessionKey") * @xmlrpc.param #param("int", "days") - * @xmlrpc.returntype array + * @xmlrpc.returntype + * #array() * $SystemOverviewSerializer + * #array_end() */ public List listInactiveSystems(String sessionKey, Integer days) { User loggedInUser = getLoggedInUser(sessionKey); diff --git a/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/config/ServerConfigHandler.java b/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/config/ServerConfigHandler.java index 084c843..3e3e09c 100644 --- a/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/config/ServerConfigHandler.java +++ b/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/config/ServerConfigHandler.java @@ -471,7 +471,6 @@ public class ServerConfigHandler extends BaseHandler { * #options() * #item_desc ("true", "to prepend the given channels * list to the top of the configuration channels list of a server") - * to the system's local override configuration channel") * #item_desc ("false", "to append the given channels * list to the bottom of the configuration channels list of a server") * #options_end() diff --git a/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/custominfo/CustomInfoHandler.java b/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/custominfo/CustomInfoHandler.java index 640fc9b..87d5aea 100644 --- a/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/custominfo/CustomInfoHandler.java +++ b/java/code/src/com/redhat/rhn/frontend/xmlrpc/system/custominfo/CustomInfoHandler.java @@ -149,8 +149,10 @@ public class CustomInfoHandler extends BaseHandler { * * @xmlrpc.doc List the custom information keys defined for the user's organization. * @xmlrpc.param #param("string", "sessionKey") - * @xmlrpc.returntype array - * $CustomDataKeySerializer + * @xmlrpc.returntype + * #array() + * $CustomDataKeySerializer + * #array_end() */ public Object[] listAllKeys(String sessionKey) throws FaultException { diff --git a/java/code/src/com/redhat/rhn/frontend/xmlrpc/systemgroup/ServerGroupHandler.java b/java/code/src/com/redhat/rhn/frontend/xmlrpc/systemgroup/ServerGroupHandler.java index 8414187..992de90 100644 --- a/java/code/src/com/redhat/rhn/frontend/xmlrpc/systemgroup/ServerGroupHandler.java +++ b/java/code/src/com/redhat/rhn/frontend/xmlrpc/systemgroup/ServerGroupHandler.java @@ -405,10 +405,7 @@ public class ServerGroupHandler extends BaseHandler { * @xmlrpc.doc Lists active systems within a server group * @xmlrpc.param #session_key() * @xmlrpc.param #param("string", "systemGroupName") - * @xmlrpc.returntype - * #array() - * int server_id - * #array_end() + * @xmlrpc.returntype #array_single("int", "server_id") */ public List<Long> listActiveSystemsInGroup(String sessionKey, String systemGroupName) { User loggedInUser = getLoggedInUser(sessionKey); @@ -435,10 +432,7 @@ public class ServerGroupHandler extends BaseHandler { * @xmlrpc.param #param("string", "systemGroupName") * @xmlrpc.param #param_desc("int", "daysInactive", "Number of days a system * must not check in to be considered inactive.") - * @xmlrpc.returntype - * #array() - * int server_id - * #array_end() + * @xmlrpc.returntype #array_single("int", "server_id") */ public List<Long> listInactiveSystemsInGroup(String sessionKey, String systemGroupName, Integer daysInactive) { @@ -459,10 +453,7 @@ public class ServerGroupHandler extends BaseHandler { * 1 day threshold. * @xmlrpc.param #session_key() * @xmlrpc.param #param("string", "systemGroupName") - * @xmlrpc.returntype - * #array() - * int server_id - * #array_end() + * @xmlrpc.returntype #array_single("int", "server_id") */ public List<Long> listInactiveSystemsInGroup(String sessionKey, String systemGroupName) { -- 1.7.7
_______________________________________________ Spacewalk-devel mailing list [email protected] https://www.redhat.com/mailman/listinfo/spacewalk-devel
