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

5 files changed, 111 insertions, 33 deletions

diff --git a/Bugzilla/WebService/Bug.pm b/Bugzilla/WebService/Bug.pm
index d60f5015b..aaaf753a3 100755
--- a/Bugzilla/WebService/Bug.pm
+++ b/Bugzilla/WebService/Bug.pm
@@ -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
+
+=back
+
 =back
 
-=item C<create> B<EXPERIMENTAL>
+=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
 
 
diff --git a/Bugzilla/WebService/Bugzilla.pm b/Bugzilla/WebService/Bugzilla.pm
index 5196834df..2f35bbe59 100755
--- a/Bugzilla/WebService/Bugzilla.pm
+++ b/Bugzilla/WebService/Bugzilla.pm
@@ -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
+
 =back
 
-=item C<timezone> B<EXPERIMENTAL>
+=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
diff --git a/Bugzilla/WebService/Product.pm b/Bugzilla/WebService/Product.pm
index 0f15a7e30..4dd894453 100755
--- a/Bugzilla/WebService/Product.pm
+++ b/Bugzilla/WebService/Product.pm
@@ -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
 
diff --git a/Bugzilla/WebService/User.pm b/Bugzilla/WebService/User.pm
index 10537138c..24b9be709 100755
--- a/Bugzilla/WebService/User.pm
+++ b/Bugzilla/WebService/User.pm
@@ -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
diff --git a/Bugzilla/WebService/Util.pm b/Bugzilla/WebService/Util.pm
index 16fea8c15..cd75bee8c 100644
--- a/Bugzilla/WebService/Util.pm
+++ b/Bugzilla/WebService/Util.pm
@@ -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