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

[Soulliere, Robert]

Thanks Galen,

Your approach of using comments with the database itself (at the source) for documentation production is the best approach.

We currently use the PostgreSQL autodoc tool to auto-generate the database schema in DocBook format for the documentation: http://docs.evergreen-ils.org/2.0/draft/html/databaseschema.html. At this time, I watered down the DocBook stylesheet to only include the database tables without comments. It has been watered down because the database schema is massive as is. Including table comments would currently includes repetitive licensing preamble for every table thus increasing the size of this appendix quite a bit.

Now I wonder if we could use the autodoc tool + comments to auto-produce documentation for comments not only for functions, but also for some table columns which might be ambiguous for users? This need seemed to come up in a recent discussion regarding importing patrons.

Would it be a useful endeavour to add comments to some of the table columns? E.g. DIG could submit SQL script patches to add the comments or could/should Developers only add them?

Thanks,
Robert

Robert Soulliere, BA (Hons), MLIS
Systems Librarian
Mohawk College Library
robert.soulliere at mohawkcollege.ca
Telephone: 905 575 1212 x3936
Fax: 905 575 2011
________________________________________
From: open-ils-dev-bounces at list.georgialibraries.org [open-ils-dev-bounces at list.georgialibraries.org] On Behalf Of Galen Charlton [gmc at esilibrary.com]
Sent: April 15, 2011 11:03 AM
To: Evergreen Development Discussion List
Cc: open-ils-documentation at list.georgialinbraries.org
Subject: Re: [OPEN-ILS-DEV] Functions for updating the call number label        or      owning_lib associated with a copy

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/


This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.