Documentation additions and fixes

Added documentation for the new object and acl list searches to
perl/Wallet/Admin.pm and server/wallet-admin.  Also fixed a POD error
in perl/Wallet/Kadmin.pm's docs.

2 files changed, 30 insertions, 10 deletions

diff --git a/perl/Wallet/Admin.pm b/perl/Wallet/Admin.pm
index 701c813..c86cbba 100644
--- a/perl/Wallet/Admin.pm
+++ b/perl/Wallet/Admin.pm
@@ -475,12 +475,14 @@ initialize() uses C<localhost> as the hostname and PRINCIPAL as the user
 when logging the history of the ADMIN ACL creation and for any subsequent
 actions on the object it returns.
 
-=item list_acls()
+=item list_acls(TYPE, SEARCH)
 
-Returns a list of all ACLs in the database.  The return value is a list of
-references to pairs of ACL ID and name.  For example, if there are two
-ACLs in the database, one with name "ADMIN" and ID 1 and one with name
-"group/admins" and ID 3, list_acls() would return:
+Returns a list of all ACLs matching a search type and string in the 
+database, or all ACLs if no search information is given.  The return value 
+is a list of references to pairs of ACL ID and name.  For example, if 
+there are two ACLs in the database, one with name "ADMIN" and ID 1 and one 
+with name "group/admins" and ID 3, list_acls() with no arguments would 
+return:
 
     ([ 1, 'ADMIN' ], [ 3, 'group/admins' ])
 
@@ -489,12 +491,20 @@ at least one ACL, but an error can be distinguished from the odd case of a
 database with no ACLs by calling error().  error() is guaranteed to return
 the error message if there was an error and undef if there was no error.
 
-=item list_objects()
+There are currently two search types.  'empty' takes no arguments, and will
+return only those acls that have no entries within them.  'entry' takes two 
+arguments -- an entry scheme and an entry identifier -- and will return 
+any ACLs with an entry that matches the given scheme and contains the
+given identifier.
 
-Returns a list of all objects in the database.  The return value is a list
-of references to pairs of type and name.  For example, if two objects
-existed in the database, both of type "keytab" and with values
-"host/example.com" and "foo", list_objects() would return:
+=item list_objects(TYPE, SEARCH)
+
+Returns a list of all objects matching a search type and string in the 
+database, or all objects in the database if no search information is 
+given.  The return value is a list of references to pairs of type and 
+name.  For example, if two objects existed in the database, both of type 
+"keytab" and with values "host/example.com" and "foo", list_objects() 
+with no arguments would return:
 
     ([ 'keytab', 'host/example.com' ], [ 'keytab', 'foo' ])
 
@@ -503,6 +513,14 @@ database containing no objects, the caller should call error().  error()
 is guaranteed to return the error message if there was an error and undef
 if there was no error.
 
+There are four types of searches currently.  'type' (with a given type)
+will return only those entries where the type matches the given type.
+'owner', with a given owner, will only return those objects owned by the
+given acl name.  'flag', with a given flag name, will only return those 
+items with a flag set to the given value.  'acl' operates like 'owner', 
+but will return only those objects that have the given acl name on any
+of the possible acl settings, not just owner.
+
 =item register_object (TYPE, CLASS)
 
 Register in the database a mapping from the object type TYPE to the class
diff --git a/perl/Wallet/Kadmin.pm b/perl/Wallet/Kadmin.pm
index 200136c..0a9bd43 100644
--- a/perl/Wallet/Kadmin.pm
+++ b/perl/Wallet/Kadmin.pm
@@ -120,6 +120,8 @@ calling valid_principal on the returned object -- this method is a shortcut
 in case we want to check validity without creating the object and worrying
 about proper setup.
 
+=back
+
 =head1 SEE ALSO
 
 kadmin(8), Wallet::Config(3), Wallet::Object::Keytab(3), wallet-backend(8)