reformatted and augmented api docs

git-svn-id: svn://svn.open-ils.org/ILS/branches/acq-experiment@8377 dcc99617-32d9-48b4-a31d-7c20da2025e4

diff --git a/Open-ILS/src/perlmods/OpenILS/Application/Acq/Financials.pm b/Open-ILS/src/perlmods/OpenILS/Application/Acq/Financials.pm
index a88aee9..696777a 100644 (file)
--- a/Open-ILS/src/perlmods/OpenILS/Application/Acq/Financials.pm
+++ b/Open-ILS/src/perlmods/OpenILS/Application/Acq/Financials.pm
@@ -28,9 +28,9 @@ sub org_descendants {
         'open-ils.storage.actor.org_unit.descendants.atomic',
         $org_id, $org->ou_type->depth);
 
-    my $org_ids = [];
-    push(@$org_ids, $_->id) for @$org_list;
-    return $org_ids;
+    my @org_ids;
+    push(@org_ids, $_->id) for @$org_list;
+    return \@org_ids;
 }
 
 
@@ -39,12 +39,12 @@ __PACKAGE__->register_method(
        method => 'create_fund',
        api_name        => 'open-ils.acq.fund.create',
        signature => {
-        desc => q/Creates a new fund/,
+        desc => 'Creates a new fund',
         params => [
-            { desc => q/Authentication token/, type => 'string' },
-            { desc => q/Fund object to create/, type => 'object' }
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Fund object to create', type => 'object'}
         ],
-        return => { desc => q/The ID of the new fund/ }
+        return => {desc => 'The ID of the new fund'}
     }
 );
 
@@ -62,11 +62,14 @@ sub create_fund {
 __PACKAGE__->register_method(
        method => 'delete_fund',
        api_name        => 'open-ils.acq.fund.delete',
-       signature => q/
-        Creates a new fund
-               @param auth Authentication token
-               @param fund
-       /
+       signature => {
+        desc => 'Deletes a fund',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Fund ID', type => 'number'}
+        ],
+        return => {desc => '1 on success, Event on failure'}
+    }
 );
 
 sub delete_fund {
@@ -83,11 +86,14 @@ sub delete_fund {
 __PACKAGE__->register_method(
        method => 'retrieve_fund',
        api_name        => 'open-ils.acq.fund.retrieve',
-       signature => q/
-        Retrieves a fund by ID
-               @param auth Authentication token
-               @param fund_id
-       /
+       signature => {
+        desc => 'Retrieves a new fund',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Fund ID', type => 'number'}
+        ],
+        return => {desc => 'The fund object on success, Event on failure'}
+    }
 );
 
 sub retrieve_fund {
@@ -102,14 +108,17 @@ sub retrieve_fund {
 __PACKAGE__->register_method(
        method => 'retrieve_org_funds',
        api_name        => 'open-ils.acq.fund.org.retrieve',
-       signature => q/
-        Retrieves all the funds associated with an org unit
-               @param auth Authentication token
-               @param org_id
-        @param options Hash of options.  Options include "children", 
-            which includes the funds for the requested org and
-            all descendant orgs.
-       /
+       signature => {
+        desc => 'Retrieves all the funds associated with an org unit',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Org Unit ID', type => 'number'},
+            {desc => 'Hash or options, including "children", which, if true,  
+                includes funds for descendant orgs in addition to the requested org', 
+            type => 'hash'},
+        ],
+        return => {desc => 'The fund objects on success, Event on failure'}
+    }
 );
 
 sub retrieve_org_funds {
@@ -132,11 +141,14 @@ sub retrieve_org_funds {
 __PACKAGE__->register_method(
        method => 'create_budget',
        api_name        => 'open-ils.acq.budget.create',
-       signature => q/
-        Creates a new budget
-               @param auth Authentication token
-               @param budget
-       /
+       signature => {
+        desc => 'Creates a new budget',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Budget object to create', type => 'object'}
+        ],
+        return => {desc => 'The ID of the newly created budget object'}
+    }
 );
 
 sub create_budget {
@@ -153,11 +165,14 @@ sub create_budget {
 __PACKAGE__->register_method(
        method => 'delete_budget',
        api_name        => 'open-ils.acq.budget.delete',
-       signature => q/
-        Deletes a budget
-               @param auth Authentication token
-               @param budget
-       /
+       signature => {
+        desc => 'Deletes a budget',
+        params => {
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Budget ID', type => 'number'}
+        },
+        return => {desc => '1 on success, Event on failure'}
+    }
 );
 
 sub delete_budget {
@@ -174,11 +189,14 @@ sub delete_budget {
 __PACKAGE__->register_method(
        method => 'retrieve_budget',
        api_name        => 'open-ils.acq.budget.retrieve',
-       signature => q/
-        Retrieves a budget by ID
-               @param auth Authentication token
-               @param budget_id
-       /
+       signature => {
+        desc => 'Retrieves a new budget',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Budget ID', type => 'number'}
+        ],
+        return => {desc => 'The budget object on success, Event on failure'}
+    }
 );
 
 sub retrieve_budget {
@@ -193,14 +211,18 @@ sub retrieve_budget {
 __PACKAGE__->register_method(
        method => 'retrieve_org_budgets',
        api_name        => 'open-ils.acq.budget.org.retrieve',
-       signature => q/
-        Retrieves all the budgets associated with an org unit 
-               @param auth Authentication token 
-               @param org_id 
-        @param options Hash of options.  Options include "children", 
-            which includes the budgets for the requested org and
-            all descendant orgs.
-       /
+       signature => {
+        desc => 'Retrieves all the budgets associated with an org unit',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Org Unit ID', type => 'number'},
+            {desc => 
+                'Options.  Options include "children", which includes
+                budgets for descendant orgs in addition to the requested org', 
+            type => 'hash'},
+        ],
+        return => {desc => 'The budget objects on success, Event on failure'}
+    }
 );
 
 sub retrieve_org_budgets {
@@ -223,11 +245,14 @@ sub retrieve_org_budgets {
 __PACKAGE__->register_method(
        method => 'create_budget_alloc',
        api_name        => 'open-ils.acq.budget_allocation.create',
-       signature => q/
-        Creates a new budget_allocation
-               @param auth Authentication token
-               @param budget_alloc
-       /
+       signature => {
+        desc => 'Creates a new budget_allocation',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Budget allocation object to create', type => 'object'}
+        ],
+        return => {desc => 'The ID of the new budget_allocation'}
+    }
 );
 
 sub create_budget_alloc {
@@ -248,11 +273,14 @@ sub create_budget_alloc {
 __PACKAGE__->register_method(
        method => 'delete_budget_alloc',
        api_name        => 'open-ils.acq.budget_allocation.delete',
-       signature => q/
-        Creates a new budget_allocation
-               @param auth Authentication token
-               @param budget_alloc
-       /
+       signature => {
+        desc => 'Deletes a budget_allocation',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Budget Alocation ID', type => 'number'}
+        ],
+        return => {desc => '1 on success, Event on failure'}
+    }
 );
 
 sub delete_budget_alloc {
@@ -272,11 +300,14 @@ sub delete_budget_alloc {
 __PACKAGE__->register_method(
        method => 'retrieve_budget_alloc',
        api_name        => 'open-ils.acq.budget_allocation.retrieve',
-       signature => q/
-        Retrieves a budget_allocation by ID
-               @param auth Authentication token
-               @param budget_alloc_id
-       /
+       signature => {
+        desc => 'Retrieves a new budget_allocation',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Budget Allocation ID', type => 'number'}
+        ],
+        return => {desc => 'The budget allocation object on success, Event on failure'}
+    }
 );
 
 sub retrieve_budget_alloc {

diff --git a/Open-ILS/src/perlmods/OpenILS/Application/Acq/Picklist.pm b/Open-ILS/src/perlmods/OpenILS/Application/Acq/Picklist.pm
index be9e53c..8201118 100644 (file)
--- a/Open-ILS/src/perlmods/OpenILS/Application/Acq/Picklist.pm
+++ b/Open-ILS/src/perlmods/OpenILS/Application/Acq/Picklist.pm
@@ -15,11 +15,14 @@ my $BAD_PARAMS = OpenILS::Event->new('BAD_PARAMS');
 __PACKAGE__->register_method(
        method => 'create_picklist',
        api_name        => 'open-ils.acq.picklist.create',
-       signature => q/
-        Creates a new picklist
-               @param authtoken
-               @param picklist
-       /
+       signature => {
+        desc => 'Creates a new picklist',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Picklist object to create', type => 'object'}
+        ],
+        return => {desc => 'The ID of the new picklist'}
+    }
 );
 
 sub create_picklist {
@@ -37,11 +40,14 @@ sub create_picklist {
 __PACKAGE__->register_method(
        method => 'update_picklist',
        api_name        => 'open-ils.acq.picklist.update',
-       signature => q/
-        Updates a picklist
-               @param authtoken
-               @param picklist
-       /
+       signature => {
+        desc => 'Updates a new picklist',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Picklist object to update', type => 'object'}
+        ],
+        return => {desc => '1 on success, Event on error'}
+    }
 );
 
 sub update_picklist {
@@ -64,13 +70,16 @@ sub update_picklist {
 __PACKAGE__->register_method(
        method => 'retrieve_picklist',
        api_name        => 'open-ils.acq.picklist.retrieve',
-       signature => q/
-        Retrieves a picklist
-               @param authtoken
-               @param picklist_id
-        @param flesh Causes the linked picklist_entry objects
-            to be appended to the object
-       /
+       signature => {
+        desc => 'Retrieves a picklist',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Picklist ID to retrieve', type => 'object'},
+            {desc => 'Options, including "flesh", which causes the picklist
+                entries to be included', type => 'hash'}
+        ],
+        return => {desc => 'Picklist object on success, Event on error'}
+    }
 );
 
 sub retrieve_picklist {
@@ -91,13 +100,15 @@ sub retrieve_picklist {
 __PACKAGE__->register_method(
        method => 'retrieve_user_picklist',
        api_name        => 'open-ils.acq.picklist.user.retrieve',
-       signature => q/
-        Retrieves all the picklists that belong to the requestor
-               @param authtoken
-        @param options A hash of retrieval options.  Options include 
-            "idlist", which causes the method to return a list of IDs
-            instead of objects;
-       /
+       signature => {
+        desc => 'Retrieves a  user\'s picklists',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Options, including "idlist", whch forces the return
+                of a list of IDs instead of objects', type => 'hash'},
+        ],
+        return => {desc => 'Picklist object on success, Event on error'}
+    }
 );
 
 sub retrieve_user_picklist {
@@ -111,11 +122,14 @@ sub retrieve_user_picklist {
 __PACKAGE__->register_method(
        method => 'delete_picklist',
        api_name        => 'open-ils.acq.picklist.delete',
-       signature => q/
-        Deletes a picklist
-               @param authtoken
-               @param picklist_id
-       /
+       signature => {
+        desc => 'Deletes a picklist',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'Picklist ID to delete', type => 'number'}
+        ],
+        return => {desc => '1 on success, Event on error'}
+    }
 );
 
 sub delete_picklist {
@@ -141,14 +155,16 @@ sub delete_picklist {
 __PACKAGE__->register_method(
        method => 'create_picklist_entry',
        api_name        => 'open-ils.acq.picklist_entry.create',
-       signature => q/
-        Creates a new picklist entry.  This method extracts the bib
-        data from the provided MARC XML.
-               @param authtoken
-               @param picklist_id
-               @param marc_xml
-               @param bibid ID of the existing bibliio.record_entry if appropriate
-       /
+       signature => {
+        desc => 'Creates a picklist entry',
+        params => [
+            {desc => 'Authentication token', type => 'string'},
+            {desc => 'ID of Picklist to attach to', type => 'number'}
+            {desc => 'MARC XML of picklist data', type => 'string'}
+            {desc => 'Bib ID of exising biblio.record_entry if appropriate', type => 'string'}
+        ],
+        return => {desc => 'ID of newly created picklist_entry on success, Event on error'}
+    }
 );
 
 sub create_picklist_entry {