caruby-core 1.5.2 → 1.5.3

data/History.md

@@ -1,6 +1,10 @@
 This history lists major release themes. See the GitHub Commits (https://github.com/caruby/core)
 for change details.
 
+1.5.3 / 2011-07-08
+------------------
+* Clean up documentation.
+
 1.5.2 / 2011-07-06
 ------------------
 * Minor gem build improvement.

data/lib/caruby/cli/application.rb

@@ -3,7 +3,7 @@ require 'caruby/util/log'
 
 module CaRuby
   module CLI
-    # Extends the standard Logger::Application to use the {CaRuby::Log} and add start
+    # Extends the standard Logger::Application to use the {Log} and add start
     # functionality.
     class Application < Logger::Application
       # @param [String] appname the application name

data/lib/caruby/csv/csvio.rb

@@ -14,7 +14,7 @@ module CaRuby
   # * allow one custom converter with different semantics: if the converter block
   #   call returns nil, then continue conversion, otherwise return the converter
   #   result. This differs from FasterCSV converter semantics which calls converters
-  #   as long the result ==  the input field value. The CsvIO converter semantics
+  #   as long the result equals the input field value. The CsvIO converter semantics
   #   supports converters that intend a String result to be the converted result.
   #
   # CsvIO is Enumerable, but does not implement the complete Ruby IO interface.
@@ -38,7 +38,7 @@ module CaRuby
       end
     end
   
-    # {#open}s the given CSV file and calls {#each} with the given block.
+    # Opens the given CSV file and calls {#each} with the given block.
     #
     # @param (see #initialize)
     # @option (see #initialize)

data/lib/caruby/database.rb

@@ -24,9 +24,9 @@ module CaRuby
   #
   # Database strives to provide a simple WYEIWYG (What You Expect Is What You Get) API, consisting of
   # the following workhorse methods:
-  # * {Query#query} - fetch domain objects which match a template
-  # * {Store#find} - fetch a specific domain object by key
-  # * {Store#store} - if a domain object exists in the database, then update it, otherwise create it
+  # * {Reader#query} - fetch domain objects which match a template
+  # * {Reader#find} - fetch a specific domain object by key
+  # * {Writer#save} - if a domain object exists in the database, then update it, otherwise create it
   #
   # Any domain object can serve as a query argument. If an optional attribute path is specified, then
   # that path is followed to the result, e.g.:
@@ -36,10 +36,10 @@ module CaRuby
   # A domain object find argument must contain enough data to determine whether it exists in the database,
   # i.e. the find argument has a database identifier or a complete secondary key.
   #
-  # The {Store#store} method creates or updates references as necessary to persist its argument domain object.
+  # The {Writer#save} method creates or updates references as necessary to persist its argument domain object.
   # It is not necessary to fetch references first or follow dependency ordering rules, which can be
   # implicit and tortuous in caBIG applications. Build the object you want to persist and call the
-  # store method. CaRuby::Resource sets reasonable default values, recognizes application dependencies and steers
+  # store method. {Resource} sets reasonable default values, recognizes application dependencies and steers
   # around caBIG idiosyncracies to the extent possible.
   class Database
     include Reader, Writer, Persistifier
@@ -92,8 +92,7 @@ module CaRuby
     #
     #   This bug might be a low-level JRuby-Java-caCORE-Hibernate confusion where something in
     #   caCORE stomps on an existing JRuby object graph. To reproduce, move the appService call
-    #   to the start_session method and run {PCBIN::MigrationTest#test_save} with all but the
-    #   verify_save(:biopsy, BIOPSY_OPTS) line commented out.
+    #   to the start_session method and run the +PSBIN::MigrationTest+ biopsy save test case.
     #
     # @param [String] service_name the name of the default {PersistenceService}
     # @param [{Symbol => String}] opts access options

data/lib/caruby/database/persistable.rb

@@ -8,8 +8,7 @@ module CaRuby
   # The Persistable mixin adds persistance capability. Every instance which includes Persistable
   # must respond to an overrided {#database} method.
   module Persistable
-    # @return [{Symbol => Object}] the content value hash at the point of the last {#take_snapshot}
-    #   call
+    # @return [{Symbol => Object}] the content value hash at the point of the last snapshot
     attr_reader :snapshot
       
     # @param [Resource, <Resource>, nil] obj the object(s) to check
@@ -198,8 +197,8 @@ module CaRuby
     end
     
     # Returns the attributes to load on demand. The base attribute list is given by the
-    # {Attributes#loadable_attributes} whose value is nil or empty.
-    # In addition, if this Persistable has more than one {Dependency#owner_attributes}
+    # {Domain::Attributes#loadable_attributes} whose value is nil or empty.
+    # In addition, if this Persistable has more than one {Domain::Dependency#owner_attributes}
     # and one is non-nil, then none of the owner attributes are loaded on demand,
     # since there can be at most one owner and ownership cannot change.
     #
@@ -233,7 +232,7 @@ module CaRuby
     end
     
     # Returns this domain object's attributes which must be fetched to reflect the database state.
-    # This default implementation returns the {Attributes#autogenerated_logical_dependent_attributes}
+    # This default implementation returns the {Domain::Attributes#autogenerated_logical_dependent_attributes}
     # if this domain object does not have an identifier, or an empty array otherwise.
     # Subclasses can override to relax or restrict the condition.
     #
@@ -262,11 +261,11 @@ module CaRuby
       end
     end
     
-    # Relaxes the {CaRuby::Persistable#saved_fetch_attributes} condition for a SCG as follows:
+    # Relaxes the {#saved_fetch_attributes} condition for a SCG as follows:
     # * If the SCG status was updated from +Pending+ to +Collected+, then fetch the saved SCG event parameters.
     # 
-    # @param (see CaRuby::Persistable#saved_fetch_attributes)
-    # @return (see CaRuby::Persistable#saved_fetch_attributes)
+    # @param (see #saved_fetch_attributes)
+    # @return (see #saved_fetch_attributes)
     def autogenerated?(operation)
       operation == :update && status_changed_to_complete? ? EVENT_PARAM_ATTRS : super
     end
@@ -309,7 +308,7 @@ module CaRuby
       ag_attrs.any? { |attr| not send(attr).nil_or_empty? }
     end
 
-    # Sets the {Attributes#volatile_nondomain_attributes} to the other fetched value,
+    # Sets the {Domain::Attributes#volatile_nondomain_attributes} to the other fetched value,
     # if different.
     #
     # @param [Resource] other the fetched domain object reflecting the database state

data/lib/caruby/database/persistence_service.rb

@@ -17,7 +17,7 @@ module CaRuby
     # The service name.
     attr_reader :name
 
-    # The {Util::Stopwatch} which captures the time spent in database operations performed by the application service.
+    # The {Stopwatch} which captures the time spent in database operations performed by the application service.
     attr_reader :timer
 
     # Creates a new PersistenceService with the specified application service name and options.

data/lib/caruby/database/reader.rb

@@ -32,7 +32,7 @@ module CaRuby
       # is a String, then the HQL statement String is executed.
       #
       # Otherwise, the query condition is determined by the values set in the template.
-      # The non-nil {Attributes#searchable_attributes} are used in the query.
+      # The non-nil {Domain::Attributes#searchable_attributes} are used in the query.
       #
       # The optional path arguments are attribute symbols from the template to the
       # destination class, e.g.:

data/lib/caruby/database/search_template_builder.rb

@@ -5,7 +5,7 @@ module CaRuby
   # SearchTemplateBuilder builds a template suitable for a caCORE saarch database operation.
   class SearchTemplateBuilder
     # Returns a template for matching the domain object obj and the optional hash values.
-    # The default hash attributes are the {Attributes#searchable_attributes}.
+    # The default hash attributes are the {Domain::Attributes#searchable_attributes}.
     # The template includes only the non-domain attributes of the hash references.
     #
     # @quirk caCORE Because of caCORE API limitations, the obj searchable attribute

data/lib/caruby/database/store_template_builder.rb

@@ -7,7 +7,7 @@ module CaRuby
     # the template are determined by the block given to this initializer, filtered as follows:
     # * If the save operation is a create, then exclude the auto-generated attributes.
     # * If the visited object has an identifier, then include only those attributes
-    #   which {Attribute#cascade_update_to_create?} or have an identifier. 
+    #   which {Domain::Attribute#cascade_update_to_create?} or have an identifier. 
     #
     # @param [Database] database the target database 
     # @yield [ref] the required selector block which determines which attributes are copied into the template
@@ -113,11 +113,11 @@ module CaRuby
     
     # Returns the attributes to visit in building the template for the given
     # domain object. The visitable attributes consist of the following:
-    # * The {Attributes#unproxied_savable_template_attributes} filtered as follows:
+    # * The {Domain::Attributes#unproxied_savable_template_attributes} filtered as follows:
     #   * If the database operation is a create, then exclude the cascaded attributes.
     #   * If the given object has an identifier, then exclude the attributes which
     #     have the the :no_cascade_update_to_create flag set.
-    # * The {Attributes#proxied_savable_template_attributes} are included if and
+    # * The {Domain::Attributes#proxied_savable_template_attributes} are included if and
     #   only if every referenced object has an identifier, and therefore does not
     #   need to be proxied.
     #
@@ -139,7 +139,7 @@ module CaRuby
     
     # Filters the given attributes, if necessary, to exclude attributes as follows:
     # * If the save operation is a create, then exclude the
-    #   {Attribute#autogenerated_on_create?} attributes.
+    #   {Domain::Attribute#autogenerated_on_create?} attributes.
     #
     # @param [Resource] obj the visited domain object
     # @param [Attributes::Filter] the savable attribute filter
@@ -155,7 +155,7 @@ module CaRuby
     # Composes the given attributes, if necessary, to exclude attributes as follows:
     # * If the save operation is a create, then exclude the auto-generated attributes.
     # * If the visited object has an identifier, then include only those attributes
-    #   which {Attribute#cascade_update_to_create?} or have an identifier. 
+    #   which {Domain::Attribute#cascade_update_to_create?} or have an identifier. 
     #
     # @param (see #mergeable_attributes)
     # @return (see #mergeable_attributes)
@@ -196,7 +196,7 @@ module CaRuby
     #   rather than the desired cascaded state. Play along with this bizarre
     #   mechanism by adding our own bizarre work-around mechanism to copy a
     #   proxied reference only if it has an identifier. This works only because
-    #   another work-around in the #{CaRuby::Database::Writer} updates proxied
+    #   another work-around in the #{Writer} updates proxied
     #   references via the proxy create before building the update template.
     def copy_proxied_save_references(obj, template)
       return unless obj.identifier

data/lib/caruby/domain/attribute.rb

@@ -245,7 +245,7 @@ module CaRuby
         @flags.include?(:autogenerated) or @flags.include?(:autogenerated_on_update)
       end
       
-      # Returns whether the the subject attribute is #{autogenerated?} for create. An attribute is
+      # Returns whether the the subject attribute is {#autogenerated?} for create. An attribute is
       # auto-generated for create if the +:autogenerate+ flag is set and the
       # +:autogenerated_on_update+ flag is not set.
       #
@@ -307,7 +307,7 @@ module CaRuby
   
       # A Java attribute is an uncreated dependent if any of the following conditions hold:
       # * the attribute is a {#logical?} dependent
-      # * the attribute is a #dependent? which is not {#creatable?}
+      # * the attribute is a {#dependent?} which is not {#creatable?}
       #
       # @return [Boolean] whether this attribute is saved in a create operation
       def uncreated_dependent?
@@ -333,7 +333,7 @@ module CaRuby
         cascaded? or @flags.include?(:include_in_save_template)
       end
       
-      # Returns whether this attribute is #{#cascaded} and cascades a parent update to a child
+      # Returns whether this attribute is #{#cascaded?} and cascades a parent update to a child
       # create. This corresponds to the Hibernate +save-update+ cascade style but not the Hibernate
       # +all+ cascade style.
       #

data/lib/caruby/domain/importer.rb

@@ -79,7 +79,7 @@ module CaRuby
       end
 
       # Configures this importer with the given options. This method is intended for use by the
-      # {#extend_module} method.
+      # +extend_module+ method.
       #
       # @param [{Symbol => Object}] opts the extension options
       # @option opts [String] :package the required Java package name

data/lib/caruby/domain/merge.rb

@@ -20,13 +20,13 @@ module CaRuby
     #
     # If other is not a Hash, then the other object's attributes values are merged into
     # this object. The default attributes is this mergeable's class
-    # {Attributes#mergeable_attributes}.
+    # {Domain::Attributes#mergeable_attributes}.
     #
     # The merge is performed by calling {#merge_attribute} on each attribute with the matches
     # and merger block given to this method.
     #
     # @param [Mergeable, {Symbol => Object}] other the source domain object or value hash to merge from
-    # @param [<Symbol>, nil] attributes the attributes to merge (default {Attributes#nondomain_attributes})
+    # @param [<Symbol>, nil] attributes the attributes to merge (default {Domain::Attributes#nondomain_attributes})
     # @param [{Resource => Resource}, nil] the optional merge source => target reference matches
     # @yield [attribute, oldval, newval] the optional merger block
     # @yieldparam [Symbol] attribute the merge target attribute

data/lib/caruby/domain/reference_visitor.rb

@@ -21,7 +21,7 @@ module CaRuby
     # Creates a new ReferenceVisitor on domain reference attributes.
     #
     # If a selector block is given to this initializer, then the reference attributes to visit
-    # are determined by calling the block. Otherwise, the {Attributes#saved_domain_attributes}
+    # are determined by calling the block. Otherwise, the {Domain::Attributes#saved_domain_attributes}
     # are visited.
     #
     # @param options (see Visitor#initialize)
@@ -70,7 +70,7 @@ module CaRuby
     end
 
     # Adds a default matcher block if necessary and delegates to {Visitor#sync}. The default matcher block
-    # calls {CaRuby::Resource#match_in} to match the candidate domain objects to visit.
+    # calls {Resource#match_in} to match the candidate domain objects to visit.
     #
     # @yield [ref, others] matches ref in others (optional)
     # @yieldparam [Resource] ref the domain object to match

data/lib/caruby/migration/migratable.rb

@@ -79,8 +79,8 @@ module CaRuby
     # Subclasses can modify this method to complete the migration. The overridden
     # methods should call +super+ to pick up the superclass migration.
     #
-    # @param [Hash] row the input row
-    # @param [Enumerable] migrated the migrated instances, including this Resource
+    # @param [{Symbol => Object}] row the input row field => value hash
+    # @param [<Resource>] migrated the migrated instances, including this domain object
     def migrate(row, migrated)
     end
 
@@ -102,8 +102,8 @@ module CaRuby
     # for the _attribute_ to modify.
     #
     # The migratable reference attributes consist of the non-collection
-    # {Attributes#saved_independent_attributes} and 
-    # {Attributes#unidirectional_dependent_attributes} which don't already have a value.
+    # {Domain::Attributes#saved_independent_attributes} and 
+    # {Domain::Attributes#unidirectional_dependent_attributes} which don't already have a value.
     # For each such migratable attribute, if there is a single instance of the attribute
     # type in the given migrated domain objects, then the attribute is set to that
     # migrated instance.

data/lib/caruby/migration/migrator.rb

@@ -27,7 +27,7 @@ module CaRuby
     # Creates a new Migrator.
     #
     # @param [{Symbol => Object}] opts the migration options
-    # @option opts [String] :database required application {CaRuby::Database}
+    # @option opts [String] :database required application {Database}
     # @option opts [String] :target required target domain class
     # @option opts [String] :mapping required input field => caTissue attribute mapping file
     # @option opts [String] :defaults optional caTissue attribute => value default mapping file

data/lib/caruby/resource.rb

@@ -40,7 +40,7 @@ module CaRuby
 
     # Sets the default attribute values for this domain object and its dependents. If this Resource
     # does not have an identifier, then missing attributes are set to the values defined by
-    # {Attributes#add_attribute_defaults}.
+    # {Domain::Attributes#add_attribute_defaults}.
     #
     # Subclasses should override the private {#add_defaults_local} method rather than this method.
     #
@@ -62,12 +62,12 @@ module CaRuby
       add_defaults_recursive
     end
 
-    # Validates this domain object and its #{Attributes.unproxied_savable_template_attributes}
+    # Validates this domain object and its #{Domain::Attributes#unproxied_savable_template_attributes}
     # for completeness prior to a database create operation.
     # An object without an identifer is valid if it contains a non-nil value for each mandatory property.
     # Objects which have an identifier or have already been validated are skipped.
     #
-    # Subclasses should not override this method, but override the private {#local_validate} instead.
+    # Subclasses should not override this method, but override the private {#validate_local} instead.
     #
     # @return [Resource] this domain object
     # @raise (see #validate_local)
@@ -120,7 +120,7 @@ module CaRuby
     # Returns a new domain object with the given attributes copied from this domain object.
     # The attributes argument consists of either attribute Symbols or a single Enumerable
     # consisting of Symbols.
-    # The default attributes are the {Attributes#nondomain_attributes}.
+    # The default attributes are the {Domain::Attributes#nondomain_attributes}.
     #
     # @param [<Symbol>, (<Symbol>)] attributes the attributes to copy
     # @return [Resource] a copy of this domain object
@@ -135,7 +135,7 @@ module CaRuby
     end
 
     # Clears the given attribute value. If the current value responds to the +clear+ method,
-    # then the current value is cleared. Otherwise, the value is set to {Metadata#empty_value}.
+    # then the current value is cleared. Otherwise, the value is set to {Domain::Metadata#empty_value}.
     #
     # @param [Symbol] attribute the attribute to clear
     def clear_attribute(attribute)
@@ -213,7 +213,7 @@ module CaRuby
     end
 
     # Returns an attribute => value hash for the specified attributes with a non-nil, non-empty value.
-    # The default attributes are this domain object's class {Attributes#attributes}.
+    # The default attributes are this domain object's class {Domain::Attributes#attributes}.
     # Only non-nil attributes defined by this Resource are included in the result hash.
     #
     # @param [<Symbol>, nil] attributes the attributes to merge
@@ -258,7 +258,7 @@ module CaRuby
     end
     
     # Returns the attributes which are required for save. This base implementation returns the
-    # class {Attributes#mandatory_attributes}. Subclasses can override this method
+    # class {Domain::Attributes#mandatory_attributes}. Subclasses can override this method
     # for domain object state-specific refinements.
     #
     # @return [<Symbol>] the required attributes for a save operation
@@ -341,7 +341,7 @@ module CaRuby
     end
 
     # Returns the difference between this Persistable and the other Persistable for the
-    # given attributes. The default attributes are the {Attributes#nondomain_attributes}.
+    # given attributes. The default attributes are the {Domain::Attributes#nondomain_attributes}.
     #
     # @param [Resource] other the domain object to compare
     # @param [<Symbol>, nil] attributes the attributes to compare
@@ -448,7 +448,7 @@ module CaRuby
 
     # Prints this domain object's content and recursively prints the referenced content.
     # The optional selector block determines the attributes to print. The default is the
-    # {Attributes#java_attributes}. The database lazy loader is disabled during
+    # {Domain::Attributes#java_attributes}. The database lazy loader is disabled during
     # the execution of this method. Thus, the printed content reflects the transient
     # in-memory object graph rather than the persistent content.
     #

data/lib/caruby/util/collection.rb

@@ -65,7 +65,7 @@ module Enumerable
   end
 
   # Returns a new Hash generated from this Enumerable with a block whose arguments include the enumerated item
-  # and its index. Every value which is {#nil_or_empty} is excluded.
+  # and its index. Every value which is nil or empty is excluded.
   #
   # @example
   #   [1, 2, 3].to_compact_hash_with_index { |item, index| item + index } #=> { 1 => 1, 2 => 3, 3 => 5 }

data/lib/caruby/version.rb

@@ -1,3 +1,3 @@
 module CaRuby
-  VERSION = "1.5.2"
+  VERSION = "1.5.3"
 end

data/test/lib/caruby/test_case.rb

@@ -35,7 +35,7 @@ module CaRuby
       assert_nothing_raised(ValidationError, msg) { subject.validate }
     end
 
-    # Tests saving the subject. Calls {Database#save} on the subject and verifies that subject and its
+    # Tests saving the subject. Calls {Database::Writer#save} on the subject and verifies that subject and its
     # references were persisted.
     #
     # @param [Resource] subject the object to save

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: caruby-core
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 5
   prerelease: false
   segments: 
   - 1
   - 5
-  - 2
-  version: 1.5.2
+  - 3
+  version: 1.5.3
 platform: ruby
 authors: 
 - OHSU
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-06 00:00:00 -07:00
+date: 2011-07-08 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency