Bommels05/Mozilla
Bommels05/Mozilla
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bug 450209: Clean up WebService POD and add a History section for all functions that need one

Browse Source 
Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=LpSolit, a=LpSolit


git-svn-id: svn://10.0.0.236/trunk@255209 18797224-902f-48f8-a5cc-f745e15eee43
This commit is contained in:
mkanat%bugzilla.org 2008-11-26 01:24:15 +00:00
parent 6e894eeb4d
commit 0f6608b369
6 changed files with 192 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
mozilla/webtools/bugzilla/Bugzilla/WebService.pm
View File

@ -159,6 +159,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

48
mozilla/webtools/bugzilla/Bugzilla/WebService/Bug.pm
View File

@ -268,14 +268,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
@ -320,11 +322,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
@ -410,7 +414,9 @@ You do not have access to the bug_id you specified.
=back
=item C<get_history> B<UNSTABLE>
=item C<get_history>
B<UNSTABLE>
=over
@ -497,9 +503,25 @@ present in this hash.
The same as L</get>.
=item B<History>
=over
=item Added in Bugzilla B<3.4>.
=back
=item C<create> B<EXPERIMENTAL>
=back
=back
=head2 Bug Creation and Modification
=over
=item C<create>
B<EXPERIMENTAL>
=over
@ -640,7 +662,9 @@ B<Required>, due to a bug in Bugzilla.
=back
=item C<add_comment> B<EXPERIMENTAL>
=item C<add_comment>
B<EXPERIMENTAL>
=over
@ -688,6 +712,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

26
mozilla/webtools/bugzilla/Bugzilla/WebService/Bugzilla.pm
View File

@ -71,12 +71,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
@ -95,7 +97,9 @@ string.
=back
=item C<extensions> B<EXPERIMENTAL>
=item C<extensions>
B<EXPERIMENTAL>
=over
@ -113,9 +117,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
=item C<timezone> B<EXPERIMENTAL>
=back
=item C<timezone>
B<STABLE>
=over
@ -129,7 +143,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

20
mozilla/webtools/bugzilla/Bugzilla/WebService/Product.pm
View File

@ -86,14 +86,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
@ -112,7 +114,9 @@ ids.
=back
=item C<get_enterable_products> B<UNSTABLE>
=item C<get_enterable_products>
B<EXPERIMENTAL>
=over
@ -132,7 +136,9 @@ ids.
=back
=item C<get_accessible_products> B<UNSTABLE>
=item C<get_accessible_products>
B<UNSTABLE>
=over
@ -152,7 +158,9 @@ ids.
=back
=item C<get> B<UNSTABLE>
=item C<get>
B<EXPERIMENTAL>
=over

39
mozilla/webtools/bugzilla/Bugzilla/WebService/User.pm
View File

@ -238,14 +238,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
@ -301,7 +303,9 @@ A login or password parameter was not provided.
=back
=item C<logout> B<EXPERIMENTAL>
=item C<logout>
B<STABLE>
=over
@ -323,7 +327,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
@ -362,7 +368,9 @@ An account with that email address already exists in Bugzilla.
=back
=item C<create> B<EXPERIMENTAL>
=item C<create>
B<EXPERIMENTAL>
=over
@ -373,6 +381,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
@ -423,7 +434,9 @@ password is over ten characters.)
=over
=item C<get> B<UNSTABLE>
=item C<get>
B<UNSTABLE>
=over
@ -465,7 +478,9 @@ each string, which defaults to 1000 but can be changed by the Bugzilla
administrator.
Logged-out users cannot use this argument, and an error will be thrown
if they try.
if they try. (This is to make it harder for spammers to harvest email
addresses from Bugzilla, and also to enforce the user visibility
restrictions that are implemented on some Bugzillas.)
=item C<include_fields> (array)
@ -564,6 +579,14 @@ function.
=back
=item B<History>
=over
=item Added in Bugzilla B<3.4>.
=back
=back
=back

11
mozilla/webtools/bugzilla/Bugzilla/WebService/Util.pm
View File

@ -12,11 +12,12 @@
#
# The Original Code is the Bugzilla Bug Tracking System.
#
# The Initial Developer of the Original Code is Everything Solved.
# Portions created by Everything Solved are Copyright (C) 2008
# Everything Solved. All Rights Reserved.
# The Initial Developer of the Original Code is Everything Solved, Inc.
# Portions created by the Initial Developer are Copyright (C) 2008
# the Initial Developer. All Rights Reserved.
#
# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
# Contributor(s):
# Max Kanat-Alexander <mkanat@bugzilla.org>
package Bugzilla::WebService::Util;
use strict;
@ -48,7 +49,7 @@ __END__
=head1 NAME
Bugzilla::WebService::Util - Utility functions used inside of the WebService
code.
code. These are B<not> functions that can be called via the WebService.
=head1 DESCRIPTION