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 [email protected] Telephone: 905 575 1212 x3936 Fax: 905 575 2011 ________________________________________ From: [email protected] [[email protected]] On Behalf Of Galen Charlton [[email protected]] Sent: April 15, 2011 11:03 AM To: Evergreen Development Discussion List Cc: [email protected] 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: [email protected] 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. _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
