caruby-tissue 1.5.4 → 1.5.5

data/lib/catissue/domain/specimen/pathology/specimen_histologic_variant_type.rb

@@ -1,6 +1,8 @@
 module CaTissue
   class Specimen
     class Pathology
+      # @quirk caTissue The 1.1 class HistologicVariantType is renamed to SpecimenHistologicVariantType in 1.2.
+      #   Alias the Ruby class constant for forward and backaward compatibility.
       begin
         resource_import Java::pathology_specimen.SpecimenHistologicVariantType
         const_set(:HistologicVariantType, SpecimenHistologicVariantType)
@@ -11,10 +13,6 @@ module CaTissue
         const_set(:SpecimenHistologicVariantType, HistologicVariantType)
         logger.debug { "Aliased the caTissue 1.1 Specimen pathology annotation class HistologicVariantType class to the renamed 1.2 SpecimenHistologicVariantType." }
       end
-      
-      # @quirk caTissue The 1.1 class HistologicVariantType is renamed to SpecimenHistologicVariantType in 1.2.
-      #   Alias the Ruby class constant for forward and backaward compatibility.
-      class SpecimenHistologicVariantType; end
     end
   end
 end

data/lib/catissue/domain/specimen/pathology/specimen_invasion.rb

@@ -1,6 +1,8 @@
 module CaTissue
   class Specimen
     class Pathology
+      # @quirk caTissue The 1.1 class Invasion is renamed to SpecimenInvasion in 1.2.
+      #   Alias the Ruby class constant for forward and backaward compatibility.
       begin
         resource_import Java::pathology_specimen.SpecimenInvasion
         const_set(:Invasion, SpecimenInvasion)
@@ -11,10 +13,6 @@ module CaTissue
         const_set(:SpecimenInvasion, Invasion)
         logger.debug { "Aliased the caTissue 1.1 Specimen pathology annotation class Invasion class to the renamed 1.2 SpecimenInvasion." }
       end
-      
-      # @quirk caTissue The 1.1 class Invasion is renamed to SpecimenInvasion in 1.2.
-      #   Alias the Ruby class constant for forward and backaward compatibility.
-      class SpecimenInvasion; end
     end
   end
 end

data/lib/catissue/domain/specimen.rb

@@ -9,40 +9,6 @@ module CaTissue
   resource_import Java::edu.wustl.catissuecore.domain.Specimen
 
   # The Specimen domain class.
-  #
-  # @quirk caTissue Specimen consent_tier_statuses is cascaded but not fetched.
-  #
-  # @quirk caTissue When a Specimen is auto-generated or created, a consent tier
-  #   status is created for each registration consent. A created Specimen has a
-  #   a well-formed status record. An auto-generated status record is malformed,
-  #   missing the Specimen id reference. This differs from the auto-generated
-  #   SCG status record, which is malformed in a different way which results in
-  #   a severe display error, as described in Bug #156. The malformed Specimen
-  #   status record results in displaying null field values in the Specimen Consent
-  #   page, but otherwise no adverse effects.
-  #
-  # @quirk caTissue Specimen position update is cascaded in Hibernate, but updateObject
-  #   is precluded by the caTissue business logic. Position change is performed by a
-  #   TransferEventParameters proxy instead. SpecimenPosition work-around is to
-  #   designate a save proxy.
-  #
-  # @quirk caTissue the Specimen parent_changed flag is ignored in a caCORE update
-  # or create Specimen argument and is set on the server. Mark the attribute as unsaved.
-  #
-  # @quirk caTissue Bug #159: Update pending Specimen ignores availableQuantity.
-  #   available_quantity is not reflected in the caCORE create or update result.
-  #   This is true even though the caTissue GUI supports available_quantity update.
-  #   Work-around is to set the :autogenerated flag, which will refetch a saved Specimen
-  #   if there is a change to the available_quantity value and will reupdate the Specimen
-  #   if the fetched available_quantity differs from the save argument value.
-  #
-  # @quirk caTissue An auto-generated Specimen auto-generates the collection and received events.
-  #   Therefore, CPR create must match the complete auto-generated SCG-Specimen-Event hierarchy.
-  #   However, SpecimenRequirement events are not auto-generated. Therefore, the AbstractSpecimen
-  #   events behavior must be specialized for Specimen but not SpecimenRequirement.
-  #
-  # @quirk caTissue remove the autogenerated blank ExternalIdentifier.
-  #   cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=436&sid=ef98f502fc0ab242781b7759a0eaff36
   class Specimen < CaTissue::AbstractSpecimen
     include Storable, Collectible
     
@@ -87,10 +53,24 @@ module CaTissue
     # Specimen children are cascaded.
     qualify_attribute(:child_specimens, :autogenerated)
 
+    # @quirk caTissue Specimen consent_tier_statuses is cascaded but not fetched.
+    #
+    # @quirk caTissue When a Specimen is auto-generated or created, a consent tier
+    #   status is created for each registration consent. A created Specimen has a
+    #   a well-formed status record. An auto-generated status record is malformed,
+    #   missing the Specimen id reference. This differs from the auto-generated
+    #   SCG status record, which is malformed in a different way which results in
+    #   a severe display error, as described in Bug #156. The malformed Specimen
+    #   status record results in displaying null field values in the Specimen Consent
+    #   page, but otherwise no adverse effects.
     add_dependent_attribute(:consent_tier_statuses, :unfetched)
 
     add_dependent_attribute(:external_identifiers)
 
+    # @quirk caTissue Specimen position update is cascaded in Hibernate, but updateObject
+    #   is precluded by the caTissue business logic. Position change is performed by a
+    #   TransferEventParameters proxy instead. SpecimenPosition work-around is to
+    #   designate a save proxy.
     add_dependent_attribute(:specimen_position)
 
     # Although label is the key, it is auto-generated if not provided in the create.
@@ -108,10 +88,22 @@ module CaTissue
     # Oddly, the seldom-used biohazards are fetched along with Specimen.
     qualify_attribute(:biohazards, :fetched)
 
+    # @quirk caTissue the Specimen parent_changed flag is ignored in a caCORE update
+    # or create Specimen argument and is set on the server. Mark the attribute as unsaved.
     qualify_attribute(:parent_changed, :unsaved)
 
+    # @quirk caTissue Bug #159: Update pending Specimen ignores availableQuantity.
+    #   available_quantity is not reflected in the caCORE create or update result.
+    #   This is true even though the caTissue GUI supports available_quantity update.
+    #   Work-around is to set the :autogenerated flag, which will refetch a saved Specimen
+    #   if there is a change to the available_quantity value and will reupdate the Specimen
+    #   if the fetched available_quantity differs from the save argument value.
     qualify_attribute(:available_quantity, :autogenerated)
 
+    # @quirk caTissue An auto-generated Specimen auto-generates the collection and received events.
+    #   Therefore, CPR create must match the complete auto-generated SCG-Specimen-Event hierarchy.
+    #   However, SpecimenRequirement events are not auto-generated. Therefore, the AbstractSpecimen
+    #   events behavior must be specialized for Specimen but not SpecimenRequirement.
     qualify_attribute(:specimen_events, :autogenerated)
     
     # The Specimen proxy class.
@@ -123,15 +115,13 @@ module CaTissue
     # Specimen storage is constrained on the basis of the +specimen_class+.
     alias :storable_type :specimen_class
 
-    # @quirk caTissue Work around caTissue Bug #64, by initializing the Specimen
-    #   consent tier statuses set.
     def initialize
       super
+      # work around caTissue Bug #64
       self.consent_tier_statuses ||= Java::JavaUtil::LinkedHashSet.new
     end
 
-    # @return [Specimen, SpecimenCollectionGroup] the parent specimen, if it exists,
-    #   otherwise the SCG
+    # Overrides {Resource#owner} to return the parent_specimen, if it exists, or the specimen_collection_group otherwise.
     def owner
       parent_specimen or specimen_collection_group
     end
@@ -146,7 +136,7 @@ module CaTissue
       collection_status == 'Collected'
     end
 
-    # Relaxes the +CaRuby::Persistable.fetch_saved?+ condition for a Specimen as follows:
+    # Relaxes the {CaRuby::Persistable#fetch_saved?} condition for a Specimen as follows:
     # * If the Specimen available_quantity was updated, then fetch the saved Specimen.
     # 
     # @return (see CaRuby::Persistable#fetch_saved)
@@ -164,6 +154,8 @@ module CaTissue
       CaTissue::CheckInCheckOutEventParameter.new(:specimen => self, :storage_status => Status.CHECKED_IN)
     end
     
+    # @quirk caTissue remove the autogenerated blank ExternalIdentifier.
+    # 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 == :external_identifiers and newval then
         CaTissue::Specimen.remove_empty_external_identifier(newval)
@@ -183,7 +175,7 @@ module CaTissue
 #      update
 #    end
 
-    # Override default +CaRuby::Resource.merge_attributes+ to ignore a source SpecimenRequirement parent_specimen.
+    # Override default {CaRuby::Resource#merge_attributes} to ignore a source SpecimenRequirement parent_specimen.
     def merge_attributes(other, attributes=nil)
       case other
         when SpecimenRequirement then
@@ -205,11 +197,9 @@ module CaTissue
       self
     end
 
-    # This method relaxes +CaRuby::Resource.match_in_owner_scope+ to include a match on at least
-    # one external identifier in the scope of an owner SCG.
-    #
-    # Wparam [<Specimen>] the specimens to match against
-    # @return [Specimen] the Specimen in others which matches this Specimen.
+    # Returns the Specimen in others which matches this Specimen in the scope of an owner SCG.
+    # This method relaxes {CaRuby::Resource#match_in_owner_scope} to include a match on at least
+    # one external identifier.
     def match_in_owner_scope(others)
       super or others.detect do |other|
         other.class == self.class and external_identifier_match?(other)

data/lib/catissue/domain/specimen_array.rb

@@ -4,8 +4,8 @@ module CaTissue
   # import the Java class
   resource_import Java::edu.wustl.catissuecore.domain.SpecimenArray
 
-  # @quirk caTissue the superclass Container occupied_positions does not apply to SpecimenArray.
   class SpecimenArray
+    # @quirk caTissue the superclass Container occupied_positions does not apply to SpecimenArray.
     remove_attribute(:occupied_positions)
  
     # Initializes this instance's child storage types from the given type.

data/lib/catissue/domain/specimen_collection_group/pathology/base_pathology_annotation.rb

@@ -3,11 +3,11 @@ module CaTissue
     class Pathology
       resource_import Java::pathology_scg.BasePathologyAnnotation
       
-      # @quirk caTissue The BasePathologyAnnotation => HistologicType collection
-      #   property is misnamed as histologicType rather than histologicTypeCollection. This misnaming
-      #   prevents caRuby from inferring the attribute domain type and inverse. Work-around is to set
-      #   these attribute features manually.
       class BasePathologyAnnotation
+        # @quirk caTissue The BasePathologyAnnotation => HistologicType collection
+        #   property is misnamed as histologicType rather than histologicTypeCollection. This misnaming
+        #   prevents caRuby from inferring the attribute domain type and inverse. Work-around is to set
+        #   these attribute features manually.
         set_attribute_type(:histologic_type, CaTissue::SpecimenCollectionGroup::Pathology::HistologicType)
         set_attribute_inverse(:histologic_type, :base_pathology_annotation)
       end

data/lib/catissue/domain/specimen_collection_group/pathology/base_solid_tissue_pathology_annotation.rb

@@ -3,11 +3,11 @@ module CaTissue
     class Pathology
       resource_import Java::pathology_scg.BaseSolidTissuePathologyAnnotation
       
-      # @quirk caTissue The BaseSolidTissuePathologyAnnotation => HistologicGrade collection
-      #   property is misnamed as histologicGrade rather than histologicGradeCollection. This misnaming
-      #   prevents caRuby from inferring the attribute domain type and inverse. Work-around is to set
-      #   these attribute features manually.
       class BaseSolidTissuePathologyAnnotation
+        # @quirk caTissue The BaseSolidTissuePathologyAnnotation => HistologicGrade collection
+        #   property is misnamed as histologicGrade rather than histologicGradeCollection. This misnaming
+        #   prevents caRuby from inferring the attribute domain type and inverse. Work-around is to set
+        #   these attribute features manually.
         set_attribute_type(:histologic_grade, CaTissue::SpecimenCollectionGroup::Pathology::HistologicGrade)
         set_attribute_inverse(:histologic_grade, :base_solid_tissue_pathology_annotation)
       end

data/lib/catissue/domain/specimen_collection_group.rb

@@ -10,45 +10,7 @@ module CaTissue
   #
   # _Note_: the SpecimenCollectionGroup name attribute is auto-generated on create in caTissue 1.1 API and should not
   # be set by API clients when creating a new SpecimenCollectionGroup in the database.
-  #
-  # @quirk caTissue Bug #116: specimen_collection_site is incorrectly attached in the caTissue class
-  #   model to AbstractSpecimenCollectionGroup rather than SpecimenCollectionGroup. CollectionProtocolEvent
-  #   is a subclass of AbstractSpecimenCollectionGroup but does not have a collection site. Therfore, the
-  #   specimen_collection_site is ignored in the caRuby AbstractSpecimenCollectionGroup class declaration
-  #   and declared as an aliased, mandatory, fetched attribute for the SpecimenCollectionGroup subclass only.
-  #
-  # @quirk caTissue An auto-generated or created SCG auto-generates a ConsentTierStatus for each
-  #   ConsentTierResponse defined in the SCG owner CPR.
-  #
-  # @quirk caTissue SCG consent_tier_statuses is cascaded but not fetched.
-  #
-  # @quirk caTissue SpecimenCollectionGroup auto-generated update ignores the referenced
-  #   specimen_event_parameters and instead creates new parameters. This occurs only on the
-  #   first update, and an SEP cannot be added to an existing, updated SCG. Work-around is
-  #   to update the SCG template without the parameters, then update the parameters separately.
-  #
-  # @quirk caTissue although SpecimenCollectionGroup auto-generated update ignores referenced
-  #   specimen_event_parameters, collection and received event parameters are mandatory for a
-  #   a created SCG. Set the +:autogenerated_on_update_only+ flag rather than the +:autogenerate+
-  #   to mark the attribute to handle this quirk.
-  #
-  # @quirk caTissue SCG specimens query result does not set the Specimen children and parent, even
-  #   though they are guaranteed to be in the SCG specimens result set. The children and parent must be
-  #   fetched separately, resulting in redundant copies of the same Specimen and additional fetches.
-  #   caRuby partially rectifies this lapse by reconciling the SCG specimens parent-child relationships
-  #   within the SCG scope.  class SpecimenCollectionGroup < CaTissue::AbstractSpecimenCollectionGroup
-  #
-  # @quirk caTissue caTissue requires that a SpecimenCollectionGroup update object references a
-  #   CollectionProtocolRegistration with a Participant reference. This is a caTissue bug, since the
-  #   CPR identifier should be sufficient for a SCG update, but caTissue bizlogic requires an extraneous
-  #   CPR -> Participant reference. The work-around is too mark the attribute with a special
-  #   +:include_in_save_template+ flag.
-  #
-  # @quirk caTissue Bug #65: Although SCG name uniquely identifies a SCG, the SCG name is auto-generated on create
-  #   and cannnot be set by the client. Therefore, name is marked as update_only.
-  #
-  # @quirk caTissue Bug #64: Initialize the SCG consent_tier_statuses to an empty set.
-  class SpecimenCollectionGroup
+  class SpecimenCollectionGroup < CaTissue::AbstractSpecimenCollectionGroup
     include Collectible
     
     # @quirk caTissue Bug #64: Some domain collection properties not initialized.
@@ -84,6 +46,11 @@ module CaTissue
       :events => :specimen_event_parameters,
       :registration => :collection_protocol_registration)
 
+    # @quirk caTissue Bug #116: specimen_collection_site is incorrectly attached in the caTissue class
+    #   model to AbstractSpecimenCollectionGroup rather than SpecimenCollectionGroup. CollectionProtocolEvent
+    #   is a subclass of AbstractSpecimenCollectionGroup but does not have a collection site. Therfore, the
+    #   specimen_collection_site is ignored in the caRuby AbstractSpecimenCollectionGroup class declaration
+    #   and declared as an aliased, mandatory, fetched attribute for the SpecimenCollectionGroup subclass only.
     add_mandatory_attributes(:specimen_collection_site, :clinical_diagnosis, :collection_status)
     
     qualify_attribute(:specimen_collection_site, :fetched)
@@ -92,6 +59,10 @@ module CaTissue
 
     set_alternate_key_attributes(:surgical_pathology_number, :collection_protocol_registration)
 
+    # @quirk caTissue An auto-generated or created SCG auto-generates a ConsentTierStatus for each
+    #   ConsentTierResponse defined in the SCG owner CPR.
+    #
+    # @quirk caTissue SCG consent_tier_statuses is cascaded but not fetched.
     add_dependent_attribute(:consent_tier_statuses, :autogenerated, :unfetched)
 
     # SCG event parameters are disjoint, since they are owned by either a SCG or a Specimen.
@@ -99,11 +70,26 @@ module CaTissue
     # A SCG SEP is only created as a dependent when the SCG is created. A SCG SEP
     # cannot be created for an existing SCG. By contrast, a Specimen SEP can only be
     # created, not updated.
+    #
+    # @quirk caTissue SpecimenCollectionGroup auto-generated update ignores the referenced
+    #   specimen_event_parameters and instead creates new parameters. This occurs only on the
+    #   first update, and an SEP cannot be added to an existing, updated SCG. Work-around is
+    #   to update the SCG template without the parameters, then update the parameters separately.
+    #
+    # @quirk caTissue although SpecimenCollectionGroup auto-generated update ignores referenced
+    #   specimen_event_parameters, collection and received event parameters are mandatory for a
+    #   a created SCG. Set the +:autogenerated_on_update_only+ flag rather than the +:autogenerate+
+    #   to mark the attribute to handle this quirk.
     add_dependent_attribute(:specimen_event_parameters, :autogenerated_on_update, :disjoint)
 
     # SCG Specimens are auto-generated from SpecimenRequirement templates when the SCG is created.
     # The Specimens are not cascaded.
     #
+    # @quirk caTissue SCG specimens query result does not set the Specimen children and parent, even
+    #   though they are guaranteed to be in the SCG specimens result set. The children and parent must be
+    #   fetched separately, resulting in redundant copies of the same Specimen and additional fetches.
+    #   caRuby partially rectifies this lapse by reconciling the SCG specimens parent-child relationships
+    #   within the SCG scope.
     add_dependent_attribute(:specimens, :logical, :autogenerated)
 
     # The CPE-SCG association is bi-directional.
@@ -112,17 +98,25 @@ module CaTissue
     # CPE is fetched but not cascaded.
     qualify_attribute(:collection_protocol_event, :fetched)
 
+    # @quirk caTissue caTissue requires that a SpecimenCollectionGroup update object references a
+    #   CollectionProtocolRegistration with a Participant reference. This is a caTissue bug, since the
+    #   CPR identifier should be sufficient for a SCG update, but caTissue bizlogic requires an extraneous
+    #   CPR -> Participant reference. The work-around is too mark the attribute with a special
+    #   +:include_in_save_template+ flag.
     qualify_attribute(:collection_protocol_registration, :include_in_save_template)
 
+    # @quirk caTissue Bug #65: Although SCG name uniquely identifies a SCG, the SCG name is auto-generated on create
+    #   and cannnot be set by the client. Therefore, name is marked as update_only.
     qualify_attribute(:name, :autogenerated, :update_only)
     
     # The SCG proxy class.
     self.annotation_proxy_class_name = 'SCGRecordEntry'
-    
+
     # The SCG pathology annotation.
     add_annotation('Pathology', :package => 'pathology_scg', :service => 'pathologySCG')
 
-     def initialize
+    # @quirk caTissue Bug #64: Initialize the SCG consent_tier_statuses to an empty set.
+    def initialize
       super
       # work around caTissue Bug #64
       self.consent_tier_statuses ||= Java::JavaUtil::LinkedHashSet.new
@@ -159,11 +153,11 @@ module CaTissue
     end
 
     # Merges the other object into this SpecimenCollectionGroup. This method augments
-    # +CaRuby::Resource.merge_attributes+ as follows:
+    # {CaRuby::Resource#merge_attributes} as follows:
     # * Adds the transitive closure of each non-derived Specimen in other.
     #
     # @param (see CaRuby::Resource#merge_attributes)
-    # @option (see Collectible#merge_attributes)
+    # @option (see CaTissue::Collectible#merge_attributes)
     def merge_attributes(other, attributes=nil)
       if Hash === other then
         # extract the event parameters
@@ -191,7 +185,7 @@ module CaTissue
       super and event_point == other.event_point
     end
 
-    # Overrides +CaRuby::Resource.direct_dependents+ in the case of the _specimens_ attribute to select
+    # Overrides {CaRuby::Resource#direct_dependents} in the case of the _specimens_ attribute to select
     # only top-level Specimens not derived from another Specimen.
     def direct_dependents(attribute)
       if attribute == :specimens then
@@ -212,7 +206,7 @@ module CaTissue
       end
     end
 
-    # Relaxes the +CaRuby::Persistable.saved_fetch_attributes+ condition for a SCG as follows:
+    # Relaxes the {CaRuby::Persistable#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)
@@ -221,7 +215,7 @@ module CaTissue
       operation == :update && status_changed_to_complete? ? EVENT_PARAM_ATTRS : super
     end
     
-    # Relaxes the +CaRuby::Persistable.saved_fetch_attributes+ condition for a SCG as follows:
+    # Relaxes the {CaRuby::Persistable#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)

data/lib/catissue/domain/specimen_protocol.rb

@@ -5,19 +5,17 @@ module CaTissue
   resource_import Java::edu.wustl.catissuecore.domain.SpecimenProtocol
   
   # The SpecimenProtocol domain class.
-  #
-  # @quirk caTissue Bug #155: enrollment is incorrectly defined in SpecimenProtocol rather
-  #   than CollectionProtocol. It is defaulted here until this defect is fixed.
-  #
-  # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
-  #   Create CollectionProtocol in API ignores startDate.
   class SpecimenProtocol
     set_secondary_key_attributes(:title)
 
+    # @quirk caTissue Bug #155: enrollment is incorrectly defined in SpecimenProtocol rather
+    #   than CollectionProtocol. It is defaulted here until this defect is fixed.
     add_attribute_defaults(:activity_status => 'Active', :enrollment => 0)
 
     add_mandatory_attributes(:principal_investigator, :activity_status, :start_date, :short_title)
 
+    # @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)
 
     private

data/lib/catissue/domain/specimen_requirement.rb

@@ -36,17 +36,14 @@ module CaTissue
     # parent CPE is created.
     qualify_attribute(:child_specimens, :logical)
     
-    # @return [SpecimenRequirement, CollectionProtocolEvent] the parent requirement,
-    #   if it is set, otherwise the collection protocol event
+    # Overrides {Resource#owner} to return the parent_specimen, if it exists, or the collection_protocol_event otherwise.
     def owner
       parent_specimen or collection_protocol_event
     end
     
-    # This method relaxes +CaRuby::Resource.match_in_owner_scope+ for a requirement that matches another requirement
-    # with the same class, specimen type, pathological_status and characteristics.
-    #
-    # @return [SpecimenRequirement] the requirement in others which matches this requirement in the scope of an
-    # owner {CollectionProtocolEvent}
+    # Returns the SpecimenRequirement in others which matches this SpecimenRequirement in the scope of an owner CollectionProtocolEvent.
+    # This method relaxes {CaRuby::Resource#match_in_owner_scope} for a SpecimenRequirement that matches any SpecimenRequirement
+    # in others with the same class, specimen type, pathological_status and characteristics.
     def match_in_owner_scope(others)
       others.detect do |other|
         self.class == other.class and specimen_type == other.specimen_type and pathological_status == other.pathological_status and
@@ -56,8 +53,7 @@ module CaTissue
 
     private
     
-    # @param [SpecimenRequirement] the requirement to match against
-    # @return [Boolean] whether this requirement's characteristics matches the other requirement's characteristics
+    # Returns whether this SpecimenRequirement characteristics matches the other SpecimenRequirement characteristics
     # on the tissue site and tissue side.
     def match_characteristics(other)
       chr = characteristics
@@ -65,17 +61,19 @@ module CaTissue
       chr and ochr and chr.tissue_side == ochr.tissue_side and chr.tissue_site == ochr.tissue_site
     end
 
-    # @raise [NotImplementedError] always, since SpecimenRequirement is abstract
+    # Raises NotImplementedError, since SpecimenRequirement is abstract.
     def self.allocate
       raise NotImplementedError.new("SpecimenRequirement is abstract; use the create method to make a new instance")
     end
 
     public
 
+    # @quirk caTissue Bug #64 - consent tier responses is not initialized to an empty set
+    #    in the Java constructor. Initialize it to a +LinkedHashSet+ in caRuby.
     def initialize
       super
+      # @quirk JRuby specimens property method is not accessible until respond_to? is called.
       respond_to?(:specimens)
-      # work around caTissue Bug #64
       self.specimens ||= Java::JavaUtil::LinkedHashSet.new
     end
 
@@ -97,15 +95,14 @@ module CaTissue
       klass.new(params.merge(:collection_protocol_event => event))
     end
 
-    # @return [CollectionProtocol, nil] the collection event protocol, if any
+    # Returns the {#collection_event} protocol, if any.
     def collection_protocol
       collection_event.protocol if collection_event
     end
 
     protected
 
-    # @quirk caTissue Overrides the CaRuby::Resource method to handle caTissue Bug #67 -
-    #   SpecimenRequirement activityStatus cannot be set.
+    # @quirk caTissue Overrides the CaRuby::Resource method to handle caTissue Bug #67 - SpecimenRequirement activityStatus cannot be set.
     #
     # @return [<Symbol>] the required attributes which are nil for this domain object
     def missing_mandatory_attributes
@@ -119,12 +116,12 @@ module CaTissue
 
     private
 
-    # @return [Boolean] whether this SpecimenRequirement has multiple non-aliquot derivatives
+    # Returns whether this SpecimenRequirement has multiple non-aliquot derivatives.
     def multiple_derivatives?
       children.size > 1 and children.any? { |drv| not drv.aliquot? }
     end
 
-    # Augments +CaRuby::Resource.validate+ to verify that this SpecimenRequirement does not have multiple non-aliquot
+    # Augments {CaRuby::Resource#validate} to verify that this SpecimenRequirement does not have multiple non-aliquot
     # derivatives, which is disallowed by caTissue.
     #
     # @quirk caTissue multiple SpecimenRequirement non-aliquot derivatives is accepted by caTissue but results