caruby-tissue 1.4.2 → 1.5.1

data/lib/catissue/domain/check_in_check_out_event_parameter.rb

@@ -2,7 +2,7 @@ module CaTissue
   # import the Java class
   resource_import Java::edu.wustl.catissuecore.domain.CheckInCheckOutEventParameter
 
-  class CheckInCheckOutEventParameter < CaTissue::SpecimenEventParameters
+  class CheckInCheckOutEventParameter
     # The check-in/check-out status permissible values.
     module Status
       CHECKED_OUT = 'CHECK OUT'

data/lib/catissue/domain/collection_event_parameters.rb

@@ -5,7 +5,7 @@ module CaTissue
   # import the Java class
   resource_import Java::edu.wustl.catissuecore.domain.CollectionEventParameters
 
-  class CollectionEventParameters < CaTissue::SpecimenEventParameters
+  class CollectionEventParameters
     include CollectibleEventParameters
     
     add_attribute_defaults(:collection_procedure => 'Not Specified', :container => 'Not Specified')

data/lib/catissue/domain/collection_protocol.rb

@@ -9,8 +9,8 @@ module CaTissue
   class CollectionProtocol
     include HashCode
     
-    # caTissue alert - Bug #64: Some domain collection properties not initialized.
-    # Initialize consent_tiers if necessary. 
+    # @quirk caTissue Bug #64: Some domain collection properties not initialized.
+    #   Initialize consent_tiers if necessary. 
     #
     # @return [Java::JavaUtil::Set] the tiers
     def consent_tiers
@@ -19,26 +19,24 @@ module CaTissue
 
     add_attribute_aliases(:events => :collection_protocol_events, :registrations => :collection_protocol_registrations)
 
-    set_secondary_key_attributes(:short_title)
-
     add_attribute_defaults(:consents_waived => false, :aliquot_in_same_container => false)
 
-    add_mandatory_attributes(:aliquot_in_same_container, :collection_protocol_events, :consents_waived, :enrollment, :start_date, :title)
+    add_mandatory_attributes(:aliquot_in_same_container, :collection_protocol_events, :consents_waived, :enrollment)
 
     add_dependent_attribute(:collection_protocol_events)
 
     add_dependent_attribute(:consent_tiers)
 
-    # caTissue alert - Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
-    # Create CollectionProtocol in API ignores startDate.
+    # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    #   Create CollectionProtocol in API ignores startDate.
     qualify_attribute(:start_date, :update_only)
 
-    # caTissue alert - Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
-    # Create CollectionProtocol in API ignores startDate.
+    # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    #   Create CollectionProtocol in API ignores startDate.
     set_attribute_type(:coordinators, CaTissue::User)
 
-    # caTissue alert - Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
-    # Create CollectionProtocol in API ignores startDate.
+    # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    #   Create CollectionProtocol in API ignores startDate.
     qualify_attribute(:coordinators, :fetched)
 
     def initialize
@@ -149,8 +147,6 @@ module CaTissue
     #   is the coordinator site.
     def add_defaults_local
       super
-      self.title ||= short_title
-      self.short_title ||= title
       self.start_date ||= Java::JavaUtil::Date.new
       if sites.empty? then add_default_site end
       if coordinators.empty? and sites.size == 1 then

data/lib/catissue/domain/collection_protocol_event.rb

@@ -9,8 +9,8 @@ module CaTissue
   class CollectionProtocolEvent
     include HashCode
     
-    # caTissue alert - Bug #64: Some domain collection properties not initialized.
-    # Initialize specimen_collection_groups if necessary.
+    # @quirk caTissue Bug #64: Some domain collection properties not initialized.
+    #    Initialize specimen_collection_groups if necessary.
     #
     # @return [Java::JavaUtil::Set] the SCGs
     def specimen_collection_groups
@@ -33,8 +33,8 @@ module CaTissue
 
     add_mandatory_attributes(:collection_protocol, :clinical_diagnosis, :specimen_requirements)
 
-    # caTissue alert - specimen_requirements is a cascaded dependent, but it is not fetched.
-    # CollectionProtocol create cascades through each dependent CPE to each SpecimenRequirement.
+    # @quirk caTissue specimen_requirements is a cascaded dependent, but it is not fetched.
+    #   CollectionProtocol create cascades through each dependent CPE to each SpecimenRequirement.
     add_dependent_attribute(:specimen_requirements, :unfetched)
 
     # The event point used for saving this CollectionProtocolEvent if none other is set.

data/lib/catissue/domain/collection_protocol_registration.rb

@@ -7,8 +7,8 @@ module CaTissue
 
   # The CollectionProtocolRegistration domain class.
   class CollectionProtocolRegistration
-    # caTissue alert - Bug #64: Some domain collection properties not initialized.
-    # Initialize consent_tier_responses if necessary. 
+    # @quirk caTissue Bug #64: Some domain collection properties not initialized.
+    #   Initialize consent_tier_responses if necessary. 
     #
     # @return [Java::JavaUtil::Set] the responses
     def consent_tier_responses
@@ -67,8 +67,8 @@ module CaTissue
     # must exist. This is checked in the special purpose {#validate_local} method.
     qualify_attribute(:protocol_participant_identifier, :optional)
 
-    # caTissue alert -  Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
-    # Create CollectionProtocol in API ignores startDate.
+    # @quirk caTissue  Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    #   Create CollectionProtocol in API ignores startDate.
     qualify_attribute(:registration_date, :update_only)
 
     def initialize

data/lib/catissue/domain/container.rb

@@ -18,14 +18,14 @@ module CaTissue
 
     add_attribute_defaults(:activity_status => 'Active', :full => false)
 
-    # caTissue alert - container capacity was auto-generated in 1.1.2, but is not in 1.2.
+    # @quirk caTissue container capacity was auto-generated in 1.1.2, but is not in 1.2.
     add_dependent_attribute(:capacity)
 
     # located_at_position is cascaded but not fetched.
     add_dependent_attribute(:located_at_position, :unfetched)
 
-    # caTissue alert - Like SCG, the Container save argument name value is ignored and assigned by caTissue
-    # to a different value instead. Therefore, this attribute is marked auto-generated.
+    # @quirk caTissue Like SCG, the Container save argument name value is ignored and assigned by caTissue
+    #   to a different value instead. Therefore, this attribute is marked auto-generated.
     qualify_attribute(:name, :autogenerated)
 
     # Returns the meta-type which constrains this Container in its role as a {Storable}
@@ -126,15 +126,6 @@ module CaTissue
       full? and subcontainers.all? { |ctr| ctr.completely_full? }
     end
 
-    # @eturn [Integer] -1, 0, or 1 if self is contained in, contains or the same as the other
-    # Container, resp.
-    def <=>(other)
-      raise TypeError.new("Can't compare #{qp} to #{other}") unless StorageContainer === self
-      return 0 if equal?(other) or (name and name == other.name)
-      return 1 if subcontainers.detect { |child| child >= other if StorageContainer === child }
-      -1 if other > self
-    end
-
     # @return [Storable, nil] the occupant at the given zero-based row and column, or nil if none
     def [](column, row)
       return if column.nil? or row.nil?
@@ -210,22 +201,22 @@ module CaTissue
     def first_available_location
       return if full?
       # look for the first unoccupied location
-      occupied = all_occupied_positions.map { |pos| pos.location }.sort
+      occd = all_occupied_positions.map { |pos| pos.location }.sort { |l1, l2| l1.coordinate <=> l2.coordinate }
       # find a gap, if one exists, otherwise return the next location
       # after the last occupied location
-      current = Location.new(:in => self, :at => Coordinate.new(0, 0))
-      occupied.each do |loc|
-        break if current < loc
-        current.succ!
+      curr = Location.new(:in => self, :at => Coordinate.new(0, 0))
+      occd.each do |loc|
+        break if curr.coordinate < loc.coordinate
+        curr.succ!
       end
-      current
+      curr
     end
 
     # Copies this Container's ContainerType capacity, if it exists, to the Container capacity.
     #
-    # caTissue alert - this method must be called by subclass initializers. The caTissue API
-    # does not make the reasonable assumption that the default Container capacity is the
-    # ContainerType capacity.
+    # @quirk caTissue this method must be called by subclass initializers. The caTissue API
+    #   does not make the reasonable assumption that the default Container capacity is the
+    #   ContainerType capacity.
     #
     # @return [Capacity, nil] the initialized capacity, if any
     def copy_container_type_capacity

data/lib/catissue/domain/container_type.rb

@@ -7,61 +7,61 @@ module CaTissue
   # The caTissue ContainerType domain class wrapper.
   # Each {ContainerType} subclass is required to implement the container_class method.
   #
-  # caTissue alert - the ContainerType and Container class hierarchy is a confusing
-  # olio of entangled relationships. The canonical use case is as follows:
-  # * A Specimen is contained in a box, vial or specimen array.
-  # * A vial or specimen array can also be placed in a box.
-  # * A frozen specimen container is placed on a rack in a freezer.
+  # @quirk caTissue the ContainerType and Container class hierarchy is a confusing
+  #   olio of entangled relationships. The canonical use case is as follows:
+  #   * A Specimen is contained in a box, vial or specimen array.
+  #   * A vial or specimen array can also be placed in a box.
+  #   * A frozen specimen container is placed on a rack in a freezer.
   #
-  # This conceptual model is implemented in caTissue as follows:
-  # * The specimen collection container type, e.g. +Citrate Vacutainer+, is captured
-  #   as a {CaTissue::CollectionEventParameters#container} String. There is no separate
-  #   collection container instance or container type instance.
-  # * A tissue specimen storage box is captured as a {CaTissue::StorageContainer}
-  #   instance constrained to a {CaTissue::StorageType} instance. Boxes with different
-  #   types are instances of the same {CaTissue::StorageContainer} class but belong 
-  #   to different {CaTissue::StorageType} instances.
-  # * {CaTissue::SpecimenArray} is a {CaTissue::Container} but not a {CaTissue::StorageContainer}.
-  #   The specimen array class is {CaTissue::SpecimenArray}, but its type is a
-  #   {CaTissue::SpecimenArrayType} instance, which is a {CaTissue::ContainerType} but not
-  #   a {CaTissue::StorageType}.
-  # * A rack is a {CaTissue::StorageContainer} instance whose type is a {CaTissue::StorageType}
-  #   instance which can hold the box {CaTissue::StorageType}.
-  # * A freezer is a {CaTissue::StorageContainer} instance whose type is a {CaTissue::StorageType}
-  #   instance which can hold the rack {CaTissue::StorageType}.
-  # * Each {CaTissue::StorageContainer} belongs to a given {CaTissue::Site}. A child
-  #   {CaTissue::StorageContainer} site defaults to its parent container site.
-  #   Site consistency is not enforced by caTissue, i.e. it is possible to create
-  #   a rack whose site differs from that of its parent freezer and child boxes.
-  # * {CaTissue::SpecimenArray} is not associated to a site.
-  # * The container children are partitioned into three methods for the three different
-  #   types and pseudo-types of contained items: {CaTissue::StorageContainer},
-  #   {CaTissue::SpecimenArray} and {CaTissue::Specimen#class}.
-  # * {CaTissue::SpecimenArray} holds {CaTissue::SpecimenArrayContent} positions, which
-  #   are the functional equivalent of {CaTissue::SpecimenPosition} adapted for specimen
-  #   arrays, although {CaTissue::SpecimenArrayContent} is not a {CaTissue::SpecimenPosition}
-  #   or even an {CaTissue::AbstractPosition}. {CaTissue::SpecimenPosition} is functionally
-  #   a specimen position in a box, whereas {CaTissue::SpecimenArrayContent} is functionally
-  #   a specimen position in a specimen array.
+  #   This conceptual model is implemented in caTissue as follows:
+  #   * The specimen collection container type, e.g. +Citrate Vacutainer+, is captured
+  #     as a {CaTissue::CollectionEventParameters#container} String. There is no separate
+  #     collection container instance or container type instance.
+  #   * A tissue specimen storage box is captured as a {CaTissue::StorageContainer}
+  #     instance constrained to a {CaTissue::StorageType} instance. Boxes with different
+  #     types are instances of the same {CaTissue::StorageContainer} class but belong 
+  #     to different {CaTissue::StorageType} instances.
+  #   * {CaTissue::SpecimenArray} is a {CaTissue::Container} but not a {CaTissue::StorageContainer}.
+  #     The specimen array class is {CaTissue::SpecimenArray}, but its type is a
+  #     {CaTissue::SpecimenArrayType} instance, which is a {CaTissue::ContainerType} but not
+  #     a {CaTissue::StorageType}.
+  #   * A rack is a {CaTissue::StorageContainer} instance whose type is a {CaTissue::StorageType}
+  #     instance which can hold the box {CaTissue::StorageType}.
+  #   * A freezer is a {CaTissue::StorageContainer} instance whose type is a {CaTissue::StorageType}
+  #     instance which can hold the rack {CaTissue::StorageType}.
+  #   * Each {CaTissue::StorageContainer} belongs to a given {CaTissue::Site}. A child
+  #     {CaTissue::StorageContainer} site defaults to its parent container site.
+  #     Site consistency is not enforced by caTissue, i.e. it is possible to create
+  #     a rack whose site differs from that of its parent freezer and child boxes.
+  #   * {CaTissue::SpecimenArray} is not associated to a site.
+  #   * The container children are partitioned into three methods for the three different
+  #     types and pseudo-types of contained items: {CaTissue::StorageContainer},
+  #     {CaTissue::SpecimenArray} and {CaTissue::Specimen#class}.
+  #   * {CaTissue::SpecimenArray} holds {CaTissue::SpecimenArrayContent} positions, which
+  #     are the functional equivalent of {CaTissue::SpecimenPosition} adapted for specimen
+  #     arrays, although {CaTissue::SpecimenArrayContent} is not a {CaTissue::SpecimenPosition}
+  #     or even an {CaTissue::AbstractPosition}. {CaTissue::SpecimenPosition} is functionally
+  #     a specimen position in a box, whereas {CaTissue::SpecimenArrayContent} is functionally
+  #     a specimen position in a specimen array.
   #
-  # The ContainerType/Container mish-mash is partially rationalized in caRuby as follows:
-  # * {CaTissue::StorageType} and {CaTissue::StorageContainer} include the
-  #   {CaTissue::StorageTypeHolder} module, which unifies treatment of contained
-  #   types.
-  # * Similarly, {CaTissue::AbstractPosition} and {CaTissue::SpecimenArrayContent} include
-  #   the {CaTissue::Position} module, which unifies treatment of positions.
-  # * Contained child types are consolidated into {CaTissue::StorageTypeHolder#child_types}.
-  # * Similarly, {CaTissue::StorageContainer} child items are consolidated into
-  #   {CaTissue::StorageContainer#child_types}.
-  # * The various container and position classes are augmented with helper methods to
-  #   add, move and find specimens and subcontainers. These methods hide the mind-numbing
-  #   eccentricity of caTissue specimen storage interaction.
-  # The entire amalgamation is further simplifying by introducing the standard Ruby
-  # container add method {CaTissue::Container::<<}. The only call the caRuby client
-  # needs to make to add a specimen box to a freezer is:
-  #   freezer << box
-  # which places the box in the first available rack slot in the freezer, or:
-  #   box >> freezer 
+  #   The ContainerType/Container mish-mash is partially rationalized in caRuby as follows:
+  #   * {CaTissue::StorageType} and {CaTissue::StorageContainer} include the
+  #     {CaTissue::StorageTypeHolder} module, which unifies treatment of contained
+  #     types.
+  #   * Similarly, {CaTissue::AbstractPosition} and {CaTissue::SpecimenArrayContent} include
+  #     the {CaTissue::Position} module, which unifies treatment of positions.
+  #   * Contained child types are consolidated into {CaTissue::StorageTypeHolder#child_types}.
+  #   * Similarly, {CaTissue::StorageContainer} child items are consolidated into
+  #     {CaTissue::StorageContainer#child_types}.
+  #   * The various container and position classes are augmented with helper methods to
+  #     add, move and find specimens and subcontainers. These methods hide the mind-numbing
+  #     eccentricity of caTissue specimen storage interaction.
+  #   The entire amalgamation is further simplifying by introducing the standard Ruby
+  #   container add method {CaTissue::Container::<<}. The only call the caRuby client
+  #   needs to make to add a specimen box to a freezer is:
+  #     freezer << box
+  #   which places the box in the first available rack slot in the freezer, or:
+  #     box >> freezer 
   class ContainerType
     add_attribute_aliases(:column_label => :oneDimensionLabel, :row_label => :twoDimensionLabel)
 
@@ -71,17 +71,17 @@ module CaTissue
 
     add_mandatory_attributes(:activity_status, :capacity, :one_dimension_label, :two_dimension_label)
 
-    # caTissue alert - although capacity is not marked cascaded in Hibernate, it is created when the
-    # ContainerType is created.
+    # @quirk caTissue although capacity is not marked cascaded in Hibernate, it is created when the
+    #   ContainerType is created.
     add_dependent_attribute(:capacity)
     
     # Override default {CaRuby::Resource#merge_attributes} to support the Capacity :rows and :columns
     # pseudo-attributes.
     #
-    # JRuby alert - Subclasses do not pick up this class's Resource method overrides.
-    # Specimen picks up the AbstractSpecimen Resource overrides, but ContainerType subclasses do
-    # not pick up ContainerType Resource overrides. Work-around is that each ContainerType
-    # subclass must alias +merge_attributes+ to this method.
+    # @quirk JRuby Subclasses do not pick up this class's Resource method overrides.
+    #   Specimen picks up the AbstractSpecimen Resource overrides, but ContainerType subclasses do
+    #   not pick up ContainerType Resource overrides. Work-around is that each ContainerType
+    #   subclass must alias +merge_attributes+ to this method.
     #
     # @param (see #merge_attributes)
     def merge_attributes(other, attributes=nil)
@@ -104,8 +104,9 @@ module CaTissue
     # @return an available container of this ContainerType which is not
     #   {CaTissue::Container#completely_full?}.
     def find_available(site, opts=nil)
+      logger.debug { "Finding an available #{site} #{self} container..." }
       find_containers(:site => site).detect { |ctr| not ctr.completely_full? } or
-      (create_container(:site => site).create if Options.get(:create, opts))
+      (new_container(:site => site).create if Options.get(:create, opts))
     end
 
     # Fetches containers of this ContainerType from the database.
@@ -113,7 +114,7 @@ module CaTissue
     # @param [<Symbol => Object>] params the optional search attribute => value hash
     # @return the containers of this type which satisfy the search parameters
     def find_containers(params=nil)
-      tmpl = create_container(params)
+      tmpl = new_container(params)
       logger.debug { "Finding #{name} containers..." }
       tmpl.query
     end
@@ -123,7 +124,7 @@ module CaTissue
     #
     # @param [{Symbol => Object}] vh the attribute => value hash
     # @return [Container] the new container
-    def create_container(vh=nil)
+    def new_container(vh=nil)
       vh ||= {}
       vh[:container_type] = self
       container_class.new(vh)
@@ -135,8 +136,8 @@ module CaTissue
     # The default {#one_dimension_label} is 'Column' if there is a non-zero dimension capacity, 'Unused' otherwise.
     # The default {#two_dimension_label} is 'Row' if there is a non-zero dimension capacity, 'Unused' otherwise.
     #
-    # JRuby alert - See {#merge_container_type_attributes}. Work-around is that each ContainerType
-    # subclass must alias +add_defaults_local+ to this method.
+    # @quirk JRuby See {#merge_container_type_attributes}. Work-around is that each ContainerType
+    #   subclass must alias +add_defaults_local+ to this method.
     def add_defaults_local
       super
       self.capacity ||= Capacity.new.add_defaults

data/lib/catissue/domain/disposal_event_parameters.rb

@@ -5,7 +5,7 @@ module CaTissue
   class DisposalEventParameters < CaTissue::SpecimenEventParameters
     add_attribute_defaults(:activity_status => 'Closed')
 
-    # caTissue alert - DisposalEventParameters activity status is transient.
+    # @quirk caTissue DisposalEventParameters activity status is transient.
     qualify_attribute(:activity_status, :unfetched)
   end
 end

data/lib/catissue/domain/hash_code.rb

@@ -1,8 +1,8 @@
 module CaTissue
   # This HashCode mix-in overrides the caTissue hashCode and equality test to work around caTissue bugs.
   module HashCode
-    # caTissue alert - caTissue hashCode changes with identifier assignment.
-    # This leads to ugly cascading errors when used in a Set or Hash.
+    # @quirk caTissue caTissue hashCode changes with identifier assignment.
+    #   This leads to ugly cascading errors when used in a Set or Hash.
     #
     # @return [Integer] a unique hash code
     # @see #==
@@ -10,10 +10,7 @@ module CaTissue
       proxy_object_id * 31 + 17
     end
 
-    # Returns whether other is of type same type as this object with the same hash as this object.
-    #
-    # caTissue alert - Bug #70: caTissue equal returns true for class mismatch.
-    #
+    # @quirk caTissue Bug #70: caTissue equal returns true for class mismatch.
     # @param other the object to compare
     # @return [Boolean] whether the objects are identical
     # @see #hash

data/lib/catissue/domain/new_specimen_array_order_item.rb

@@ -6,16 +6,16 @@ module CaTissue
 
   # The NewSpecimenArrayOrderItem domain class.
   class NewSpecimenArrayOrderItem
-    # caTissue alert - Bug #64: Some domain collection properties not initialized.
-    # Initialize order_items if necessary. 
+    # @quirk caTissue Bug #64: Some domain collection properties not initialized.
+    #   Initialize order_items if necessary. 
     #
     # @return [Java::JavaUtil::Set] the items
     def order_items
       getOrderItemCollection or (self.order_items = Java::JavaUtil::LinkedHashSet.new)
     end
     
-    # caTissue alert - Bug #64: Some domain collection properties not initialized.
-    # Initialize distributions if necessary. 
+    # @quirk caTissue Bug #64: Some domain collection properties not initialized.
+    #   Initialize distributions if necessary. 
     def distributions
       getDistributionCollection or (self.distributions = Java::JavaUtil::LinkedHashSet.new)
     end

data/lib/catissue/domain/order_details.rb

@@ -5,8 +5,8 @@ module CaTissue
 
   # The OrderDetails domain class.
   class OrderDetails
-    # caTissue alert - Bug #64: Some domain collection properties not initialized.
-    # Initialize order_items if necessary. 
+    # @quirk caTissue Bug #64: Some domain collection properties not initialized.
+    #   Initialize order_items if necessary. 
     #
     # @return [Java::JavaUtil::Set] the items
     def order_items
@@ -16,7 +16,7 @@ module CaTissue
     def initialize
       super
       respond_to?(:order_items)
-      # caTissue alert - work around caTissue Bug #64
+      # @quirk caTissue work around caTissue Bug #64
       self.order_items ||= Java::JavaUtil::LinkedHashSet.new
     end
   end

data/lib/catissue/domain/participant.rb

@@ -12,9 +12,9 @@ module CaTissue
 
     # The convenience Person name aggregate is not a Java property but is added as a transient attribute
     # which is reflected in the saved Java property name subfields.
-    add_attribute(:name)
+    add_attribute(:name, CaRuby::Person::Name)
 
-    # caTissue alert - clinical study is unsupported by 1.1.x caTissue, removed in 1.2.
+    # @quirk caTissue clinical study is unsupported by 1.1.x caTissue, removed in 1.2.
     if attribute_defined?(:clinical_study_registrations) then remove_attribute(:clinical_study_registrations) end
 
     add_attribute_aliases(:collection_registrations => :collection_protocol_registrations,
@@ -30,32 +30,35 @@ module CaTissue
     add_attribute_defaults(:activity_status => 'Active', :ethnicity => 'Unknown', :gender => 'Unspecified',
       :sex_genotype => 'Unknown', :vital_status => 'Unknown')
 
-    # caTissue alert - Bug #154: Participant gender is specified by caTissue as optional, but if it is not set then
-    # it appears as Female in the GUI even though it is null in the database.
+    # @quirk caTissue Bug #154: Participant gender is specified by caTissue as optional, but if it is not set then
+    #   it appears as Female in the GUI even though it is null in the database.
     add_mandatory_attributes(:activity_status, :gender)
 
-    # caTissue alert - Participant CPR cascade is simulated in the bizlogic.
-    # See the PMI comment below.
+    # @quirk caTissue Participant CPR cascade is simulated in the bizlogic.
+    #   See the PMI comment below.
     add_dependent_attribute(:collection_protocol_registrations)
 
     add_dependent_attribute(:races)
 
-    # caTissue alert - Participant PMI is fetched but not cascaded. However, the Participant bizlogic
-    # simulates PMI cascade. The bizlogic doesn't document why this is done, but it appears that the
-    # reason is to inject an empty PMI if necessary in order to work around a caTissue query bug
-    # (see merge_attribute comment). At any rate, mark PMI as cascaded in the caRuby metadata
-    # to reflect the bizlogic simulation. However, this designation should be revisited with each
-    # release, since if the bizlogic hack is removed then caRuby Participant PMI save will break.
+    # @quirk caTissue Participant PMI is fetched but not cascaded. However, the Participant bizlogic
+    #   simulates PMI cascade. The bizlogic doesn't document why this is done, but it appears that the
+    #   reason is to inject an empty PMI if necessary in order to work around a caTissue query bug
+    #   (see merge_attribute comment). At any rate, mark PMI as cascaded in the caRuby metadata
+    #   to reflect the bizlogic simulation. However, this designation should be revisited with each
+    #   release, since if the bizlogic hack is removed then caRuby Participant PMI save will break.
     add_dependent_attribute(:participant_medical_identifiers)
 
     # SSN is a key, if present, but is not required.
     qualify_attribute(:social_security_number, :optional)
     
+    # The Participant proxy class.
+    self.annotation_proxy_class_name = 'ParticipantRecordEntry'
+    
     # The clinicial annotation.
-    add_annotation('Clinical', :package => 'clinical_annotation', :service => 'CA', :record_entry => 'ParticipantRecordEntry')
+    add_annotation('Clinical', :package => 'clinical_annotation', :service => 'CA')
 
-    # caTissue alert - remove the autogenerated blank PMI.
-    # cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=436&sid=ef98f502fc0ab242781b7759a0eaff36
+    # @quirk caTissue remove the autogenerated blank PMI.
+    #   cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=436&sid=ef98f502fc0ab242781b7759a0eaff36
     def merge_attribute(attribute, newval, matches=nil)
       if attribute == :participant_medical_identifiers and newval then
         CaTissue::Participant.remove_empty_medical_identifier(newval)
@@ -63,24 +66,26 @@ module CaTissue
       super
     end
 
-    # Returns the SSN if it exists, otherwise the first ParticipantMedicalIdentifier, if any, otherwise nil.
+    # @return the SSN if it exists, otherwise the first ParticipantMedicalIdentifier, if any, otherwise nil
     def key
       super or medical_identifiers.first
     end
 
-    # Returns a new ParticipantMedicalIdentifier which adds this Participant to the given site
-    # with Medical Record Number mrn.
+    # @param [CaTissue::Site] the registration site
+    # @param [String] mrn the registration MRN
+    # @return [CaTissue::ParticipantMedicalIdentifier] a new PMI which adds this Participant to the site
+    #   with the MRN
     def add_mrn(site, mrn)
       CaTissue::ParticipantMedicalIdentifier.new(:participant => self, :site => site, :medical_record_number => mrn)
     end
 
-    # Returns this Participant's medical record numbers. Each medical record number is Site-specific.
+    # @return [<String>] this Participant's medical record numbers. Each medical record number is site-specific.
     # @see the medical_identifiers attribute for MRN-site associations
     def medical_record_numbers
       medical_identifiers.map { |pmi| pmi.medicalRecordNumber }
     end
 
-    # Returns all specimens collected from this Participant.
+    # @return [<CTissue::Specimen>] all specimens collected from this participant
     def specimens
       Flattener.new(registrations.specimens.map { |cpr| cpr.specimens })
     end
@@ -93,6 +98,7 @@ module CaTissue
     # Returns the MRN for this participant. If this Participant does not have exactly one
     # MRN, then this method returns nil. This method is a convenience for the common situation
     # where a participant is enrolled at one site.
+    # @return [String] the MRN
     def medical_record_number
       return medical_identifiers.first.medical_record_number if medical_identifiers.size == 1
     end
@@ -100,6 +106,8 @@ module CaTissue
     # Returns the collection site for which this participant has a MRN. If there is not exactly one
     # such site, then this method returns nil. This method is a convenience for the common situation
     # where a participant is enrolled at one site.
+    #
+    # @return [CaTissue::Site] the collection site
     def collection_site
       return unless medical_identifiers.size == 1
       site = medical_identifiers.first.site