[OPEN-ILS-DEV] Functions for updating the call number label or owning_lib associated with a copy

[Galen Charlton]

Hi,

On Apr 15, 2011, at 8:31 AM, Soulliere, Robert wrote:

> In regards to documentation, I wonder if an official procedures or documentation formats could be in place for developers to ensure that basic documentation is provided on purpose and basic usage for any new tools, functions or resources for Evergreen. I can see these db functions being very valuable for Evergreen users, but they would even be more valuable to the common user if they are well documented quickly so that they find their way to the official documentation so all users can find out about them. E.g. could it be required that any new evergreen feature be submitted with a one page AsciiDoc document explaining the purpose, usage and parameters of a feature/function/etc...

Agreed regarding the utility of encouraging at least minimal documentation to be submitted when a developer pushes a new feature.  In the specific case of stored procedures (and other database objects), Postgres supports attaching comments that describe the purpose of the function.  Look towards the bottom of:

http://git.esilibrary.com/?p=evergreen-equinox.git;a=commitdiff;h=84f6c978b57ae71e1ce58ac04d4b3eb284c681ad

This kind of comment has a couple nice properties.  First, it can be displayed at the point of use using psql's \dd command:

gmc1=# \dd munge.change_copy_call_number 
Object descriptions
-[ RECORD 1 ]-------------------------------------------------------------------
Schema      | munge
Name        | change_copy_call_number
Object      | function
Description | 
            : Change the call number label associated with the specified item,
            : creating, relinking, and deleting volume records as needed.  The
            : call number associated with any other items attached to the target
            : item's original volume will remain unchanged.
            : 
            : Accepts the following parameters:
            : 
            : copy_id   - asset.copy.id of the copy to change
            : new_label - new call number string
            : 
            : The return value is a boolean indicating whether the copy call
            : number was changed or not.
            : 
            : This routine will refuse to touch or create located URIs.
            : 

Also, since the comments stored in the database, it's easy for schema analysis tools to get at them.  In fact, a function to spit out database object comments in AsciiDoc in a format suitable for DIG's needs sounds like a good idea for a munge function.

Regards,

Galen
--
Galen Charlton
VP, Data Services
Equinox Software, Inc. / Your Library's Guide to Open Source
email:  gmc at esilibrary.com
direct: +1 352-215-7548
skype:  gmcharlt
web:    http://www.esilibrary.com/