From: mkanat%bugzilla.org <>
Date: Wed, 26 Nov 2008 01:24:14 +0000 (+0000)
Subject: Bug 450209: Clean up WebService POD and add a History section for all functions that... 
X-Git-Tag: bugzilla-3.2~3
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e2db9567c3497d94bb4b145526c2cdaeb9067ced;p=thirdparty%2Fbugzilla.git

Bug 450209: Clean up WebService POD and add a History section for all functions that need one
Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=LpSolit, a=LpSolit
---

diff --git a/Bugzilla/WebService.pm b/Bugzilla/WebService.pm
index 5eb86a8d04..0e429241d6 100755
--- a/Bugzilla/WebService.pm
+++ b/Bugzilla/WebService.pm
@@ -150,6 +150,87 @@ Bugzilla::WebService - The Web Service interface to Bugzilla
 This is the standard API for external programs that want to interact
 with Bugzilla. It provides various methods in various modules.
 
+Currently the only method of accessing the API is via XML-RPC. The XML-RPC
+standard is described here: L<http://www.xmlrpc.com/spec>
+
+The endpoint for Bugzilla WebServices is the C<xmlrpc.cgi> script in
+your Bugzilla installation. For example, if your Bugzilla is at
+C<bugzilla.yourdomain.com>, then your XML-RPC client would access the
+API via: C<http://bugzilla.yourdomain.com/xmlrpc.cgi>
+
+=head1 CALLING METHODS
+
+Methods are called in the normal XML-RPC fashion. Bugzilla does not currently
+implement any extensions to the standard method of XML-RPC method calling.
+
+Methods are grouped into "packages", like C<Bug> for 
+L<Bugzilla::WebService::Bug>. So, for example,
+L<Bugzilla::WebService::Bug/get>, is called as C<Bug.get> in XML-RPC.
+
+=head1 PARAMETERS
+
+In addition to the standard parameter types like C<int>, C<string>, etc.,
+XML-RPC has two data structures, a C<< <struct> >> and an C<< <array> >>.
+
+=head2 Structs
+
+In Perl, we call a C<< <struct> >> a "hash" or a "hashref". You may see
+us refer to it that way in the API documentation.
+
+In example code, you will see the characters C<{> and C<}> used to represent
+the beginning and end of structs.
+
+For example, here's a struct in XML-RPC:
+
+ <struct>
+   <member>
+     <name>fruit</name>
+     <value><string>oranges</string></value>
+   </member>
+   <member>
+     <name>vegetable</name>
+     <value><string>lettuce</string></value>
+   </member>
+ </struct>
+
+In our example code in these API docs, that would look like:
+
+ { fruit => 'oranges', vegetable => 'lettuce' }
+
+=head2 Arrays
+
+In example code, you will see the characters C<[> and C<]> used to
+represent the beginning and end of arrays.
+
+For example, here's an array in XML-RPC:
+
+ <array>
+   <data>
+     <value><i4>1</i4></value>
+     <value><i4>2</i4></value>
+     <value><i4>3</i4></value>
+   </data>
+ </array>
+
+In our example code in these API docs, that would look like:
+
+ [1, 2, 3]
+
+=head2 How Bugzilla WebService Methods Take Parameters
+
+B<All> Bugzilla WebServices functions take their parameters in
+a C<< <struct> >>. Another way of saying this would be: All functions
+take a single argument, a C<< <struct> >> that contains all parameters.
+The names of the parameters listed in the API docs for each function are
+the C<name> element for the struct C<member>s.
+
+=head1 LOGGING IN
+
+You can use L<Bugzilla::WebService::User/login> to log in as a Bugzilla 
+user. This issues standard HTTP cookies that you must then use in future
+calls, so your XML-RPC client must be capable of receiving and transmitting
+cookies.
+
 =head1 STABLE, EXPERIMENTAL, and UNSTABLE
 
 Methods are marked B<STABLE> if you can expect their parameters and
diff --git a/Bugzilla/WebService/Bug.pm b/Bugzilla/WebService/Bug.pm
index e8b7dd3e49..5df7c7d196 100755
--- a/Bugzilla/WebService/Bug.pm
+++ b/Bugzilla/WebService/Bug.pm
@@ -225,14 +225,16 @@ or get information about bugs that have already been filed.
 
 =head1 METHODS
 
-See L<Bugzilla::WebService> for a description of B<STABLE>, B<UNSTABLE>,
-and B<EXPERIMENTAL>.
+See L<Bugzilla::WebService> for a description of how parameters are passed,
+and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.
 
 =head2 Utility Functions
 
 =over
 
-=item C<legal_values> B<EXPERIMENTAL>
+=item C<legal_values> 
+
+B<EXPERIMENTAL>
 
 =over
 
@@ -277,11 +279,13 @@ You specified a field that doesn't exist or isn't a drop-down field.
 
 =back
 
-=head2 Bug Creation and Modification
+=head2 Bug Information
 
 =over
 
-=item C<get> B<EXPERIMENTAL>
+=item C<get> 
+
+B<EXPERIMENTAL>
 
 =over
 
@@ -367,7 +371,12 @@ You do not have access to the bug_id you specified.
 
 =back
 
+=back
+
+
+=head2 Bug Creation and Modification
 
+=over
 
 =item C<create> B<EXPERIMENTAL>
 
@@ -510,7 +519,9 @@ B<Required>, due to a bug in Bugzilla.
 
 =back
 
-=item C<add_comment> B<EXPERIMENTAL>
+=item C<add_comment> 
+
+B<EXPERIMENTAL>
 
 =over
 
@@ -558,6 +569,14 @@ You did not have the necessary rights to edit the bug.
 
 =back
 
+=item B<History>
+
+=over
+
+=item Added in Bugzilla B<3.2>.
+
+=back
+
 =back
 
 
diff --git a/Bugzilla/WebService/Bugzilla.pm b/Bugzilla/WebService/Bugzilla.pm
index 7b58af2540..53e0d7d79a 100755
--- a/Bugzilla/WebService/Bugzilla.pm
+++ b/Bugzilla/WebService/Bugzilla.pm
@@ -69,12 +69,14 @@ This provides functions that tell you about Bugzilla in general.
 
 =head1 METHODS
 
-See L<Bugzilla::WebService> for a description of what B<STABLE>, B<UNSTABLE>,
-and B<EXPERIMENTAL> mean.
+See L<Bugzilla::WebService> for a description of how parameters are passed,
+and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.
 
 =over
 
-=item C<version> B<EXPERIMENTAL>
+=item C<version>
+
+B<STABLE>
 
 =over
 
@@ -93,7 +95,9 @@ string.
 
 =back
 
-=item C<extensions> B<EXPERIMENTAL>
+=item C<extensions>
+
+B<EXPERIMENTAL>
 
 =over
 
@@ -111,9 +115,19 @@ contains the names of extensions as keys, and information about the extension
 as values. One of the values that must be returned is the 'version' of the
 extension
 
+=item B<History>
+
+=over
+
+=item Added in Bugzilla B<3.2>.
+
+=back
+
 =back
 
-=item C<timezone> B<EXPERIMENTAL>
+=item C<timezone>
+
+B<STABLE>
 
 =over
 
@@ -127,7 +141,7 @@ returns will be in this timezone.
 
 =item B<Returns>
 
-A hash with a single item, C<timezone>, that is the timezone as a
+A hash with a single item, C<timezone>, that is the timezone offset as a
 string in (+/-)XXXX (RFC 2822) format.
 
 =back
diff --git a/Bugzilla/WebService/Product.pm b/Bugzilla/WebService/Product.pm
index 995e0adc02..cd86296a44 100755
--- a/Bugzilla/WebService/Product.pm
+++ b/Bugzilla/WebService/Product.pm
@@ -87,14 +87,16 @@ get information about them.
 
 =head1 METHODS
 
-See L<Bugzilla::WebService> for a description of what B<STABLE>, B<UNSTABLE>,
-and B<EXPERIMENTAL> mean, and for more information about error codes.
+See L<Bugzilla::WebService> for a description of how parameters are passed,
+and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.
 
 =head2 List Products
 
 =over
 
-=item C<get_selectable_products> B<UNSTABLE>
+=item C<get_selectable_products> 
+
+B<EXPERIMENTAL>
 
 =over
 
@@ -113,7 +115,9 @@ ids.
 
 =back
 
-=item C<get_enterable_products> B<UNSTABLE>
+=item C<get_enterable_products> 
+
+B<EXPERIMENTAL>
 
 =over
 
@@ -133,7 +137,9 @@ ids.
 
 =back
 
-=item C<get_accessible_products> B<UNSTABLE>
+=item C<get_accessible_products> 
+
+B<UNSTABLE>
 
 =over
 
@@ -153,7 +159,9 @@ ids.
 
 =back
 
-=item C<get> B<UNSTABLE>
+=item C<get> 
+
+B<EXPERIMENTAL>
 
 =over
 
diff --git a/Bugzilla/WebService/User.pm b/Bugzilla/WebService/User.pm
index cab2c5182b..5446d804fa 100755
--- a/Bugzilla/WebService/User.pm
+++ b/Bugzilla/WebService/User.pm
@@ -140,14 +140,16 @@ log in/out using an existing account.
 
 =head1 METHODS
 
-See L<Bugzilla::WebService> for a description of what B<STABLE>, B<UNSTABLE>,
-and B<EXPERIMENTAL> mean, and for more information about error codes.
+See L<Bugzilla::WebService> for a description of how parameters are passed,
+and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.
 
 =head2 Logging In and Out
 
 =over
 
-=item C<login> B<EXPERIMENTAL>
+=item C<login> 
+
+B<STABLE>
 
 =over
 
@@ -203,7 +205,9 @@ A login or password parameter was not provided.
 
 =back
 
-=item C<logout> B<EXPERIMENTAL>
+=item C<logout> 
+
+B<STABLE>
 
 =over
 
@@ -225,7 +229,9 @@ Log out the user. Does nothing if there is no user logged in.
 
 =over
 
-=item C<offer_account_by_email> B<EXPERIMENTAL>
+=item C<offer_account_by_email> 
+
+B<STABLE>
 
 =over
 
@@ -264,7 +270,9 @@ An account with that email address already exists in Bugzilla.
 
 =back
 
-=item C<create> B<EXPERIMENTAL>
+=item C<create> 
+
+B<EXPERIMENTAL>
 
 =over
 
@@ -275,6 +283,9 @@ Instead of this, you should use L</offer_account_by_email> when
 possible, because that makes sure that the email address specified can
 actually receive an email. This function does not check that.
 
+You must be logged in and have the C<editusers> privilege in order to
+call this function.
+
 =item B<Params>
 
 =over
@@ -317,6 +328,14 @@ password is over ten characters.)
 
 =back
 
+=item B<History>
+
+=over
+
+=item Added in Bugzilla B<3.4>.
+
+=back
+
 =back
 
 =back