rtp-connect 1.1 → 1.2

data/lib/rtp-connect/prescription.rb

@@ -2,10 +2,9 @@ module RTP
 
   # The Prescription site class.
   #
-  # === Relations
-  #
-  # * Parent: Plan
-  # * Children: SiteSetup, (SimulationField), Field
+  # @note Relations:
+  #   * Parent: Plan
+  #   * Children: SiteSetup, Field
   #
   class Prescription < Record
 
@@ -29,10 +28,10 @@ module RTP
 
     # Creates a new Prescription site by parsing a RTPConnect string line.
     #
-    # === Parameters
-    #
-    # * <tt>string</tt> -- A string containing a prescription site record.
-    # * <tt>parent</tt> -- A Record which is used to determine the proper parent of this instance.
+    # @param [#to_s] string the prescription site definition record string line
+    # @param [Record] parent a record which is used to determine the proper parent of this instance
+    # @return [Prescription] the created Precription instance
+    # @raise [ArgumentError] if given a string containing an invalid number of elements
     #
     def self.load(string, parent)
       # Get the quote-less values:
@@ -58,9 +57,7 @@ module RTP
 
     # Creates a new Prescription site.
     #
-    # === Parameters
-    #
-    # * <tt>parent</tt> -- A Record which is used to determine the proper parent of this instance.
+    # @param [Record] parent a record which is used to determine the proper parent of this instance
     #
     def initialize(parent)
       # Child objects:
@@ -72,7 +69,13 @@ module RTP
       @keyword = 'RX_DEF'
     end
 
-    # Returns true if the argument is an instance with attributes equal to self.
+    # Checks for equality.
+    #
+    # Other and self are considered equivalent if they are
+    # of compatible types and their attributes are equivalent.
+    #
+    # @param other an object to be compared with self.
+    # @return [Boolean] true if self and other are considered equivalent
     #
     def ==(other)
       if other.respond_to?(:to_prescription)
@@ -82,32 +85,44 @@ module RTP
 
     alias_method :eql?, :==
 
-    # Adds a treatment Field record to this instance.
+    # Adds a treatment field record to this instance.
+    #
+    # @param [Field] child a Field instance which is to be associated with self
     #
     def add_field(child)
       @fields << child.to_field
     end
 
-    # Connects a Site setup record to this instance.
+    # Adds a site setup record to this instance.
+    #
+    # @param [SiteSetup] child a SiteSetup instance which is to be associated with self
     #
     def add_site_setup(child)
       @site_setup = child.to_site_setup
     end
 
-    # Returns the a properly sorted array of the child records of this instance.
+    # Collects the child records of this instance in a properly sorted array.
+    #
+    # @return [Array<SiteSetup, Field>] a sorted array of self's child records
     #
     def children
       return [@site_setup, @fields].flatten.compact
     end
 
-    # Generates a Fixnum hash value for this instance.
+    # Computes a hash code for this object.
+    #
+    # @note Two objects with the same attributes will have the same hash code.
+    #
+    # @return [Fixnum] the object's hash code
     #
     def hash
       state.hash
     end
 
-    # Returns the values of this instance in an array.
-    # The values does not include the CRC.
+    # Collects the values (attributes) of this instance.
+    #
+    # @note The CRC is not considered part of the actual values and is excluded.
+    # @return [Array<String>] an array of attributes (in the same order as they appear in the RTP string)
     #
     def values
       return [
@@ -128,13 +143,17 @@ module RTP
 
     # Returns self.
     #
+    # @return [Prescription] self
+    #
     def to_prescription
       self
     end
 
-    # Writes the Prescription object + any hiearchy of child objects,
+    # Encodes the Prescription object + any hiearchy of child objects,
     # to a properly formatted RTPConnect ascii string.
     #
+    # @return [String] an RTP string with a single or multiple lines/records
+    #
     def to_s
       str = encode
       if children
@@ -149,6 +168,10 @@ module RTP
 
     # Sets the keyword attribute.
     #
+    # @note Since only a specific string is accepted, this is more of an argument check than a traditional setter method
+    # @param [#to_s] value the new attribute value
+    # @raise [ArgumentError] if given an unexpected keyword
+    #
     def keyword=(value)
       value = value.to_s.upcase
       raise ArgumentError, "Invalid keyword. Expected 'RX_DEF', got #{value}." unless value == "RX_DEF"
@@ -157,75 +180,100 @@ module RTP
 
     # Sets the course_id attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def course_id=(value)
       @course_id = value && value.to_s
     end
 
     # Sets the rx_site_name attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def rx_site_name=(value)
       @rx_site_name = value && value.to_s
     end
 
     # Sets the technique attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def technique=(value)
       @technique = value && value.to_s
     end
 
     # Sets the modality attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def modality=(value)
       @modality = value && value.to_s
     end
 
     # Sets the dose_spec attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def dose_spec=(value)
       @dose_spec = value && value.to_s
     end
 
     # Sets the rx_depth attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def rx_depth=(value)
       @rx_depth = value && value.to_s
     end
 
     # Sets the dose_ttl attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def dose_ttl=(value)
-      @dose_ttl = value && value.to_s
+      @dose_ttl = value && value.to_s.strip
     end
 
     # Sets the dose_tx attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def dose_tx=(value)
-      @dose_tx = value && value.to_s
+      @dose_tx = value && value.to_s.strip
     end
 
     # Sets the pattern attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def pattern=(value)
       @pattern = value && value.to_s
     end
 
     # Sets the rx_note attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def rx_note=(value)
       @rx_note = value && value.to_s
     end
 
     # Sets the number_of_fields attribute.
     #
+    # @param [nil, #to_s] value the new attribute value
+    #
     def number_of_fields=(value)
-      @number_of_fields = value && value.to_s
+      @number_of_fields = value && value.to_s.strip
     end
 
 
     private
 
 
-    # Returns the attributes of this instance in an array (for comparison purposes).
+    # Collects the attributes of this instance.
+    #
+    # @note The CRC is not considered part of the attributes of interest and is excluded
+    # @return [Array<String>] an array of attributes
     #
     alias_method :state, :values
 

data/lib/rtp-connect/record.rb

@@ -1,18 +1,29 @@
 module RTP
 
+  # The Record class contains attributes and methods that are common
+  # for the various record types defined in the RTPConnect standard.
+  #
   class Record
 
+    # The keyword defines the record type of a particular RTP string line.
     attr_reader :keyword
+    # The CRC is used to validate the integrity of the content of the RTP string line.
     attr_reader :crc
 
-    # Setting the keyword attribute.
+    # Sets the crc (checksum) attribute.
+    #
+    # @note This value is not used when creating an RTP string from a record (a new crc is calculated)
+    # @param [#to_s] value the new attribute value
     #
     def crc=(value)
       @crc = value.to_s
     end
 
     # Encodes a string from the contents of this instance.
-    # This produces the full line, including a computed CRC checksum.
+    #
+    # This produces the full record string line, including a computed CRC checksum.
+    #
+    # @return [String] a proper RTPConnect type CSV string
     #
     def encode
       content = values.encode + ","
@@ -23,6 +34,9 @@ module RTP
 
     # Follows the tree of parents until the appropriate parent of the requesting record is found.
     #
+    # @param [Record] last_parent the previous parent (the record from the previous line in the RTP file)
+    # @param [Record] klass the expected parent record class of this record (e.g. Plan, Field)
+    #
     def get_parent(last_parent, klass)
       if last_parent.is_a?(klass)
         return last_parent
@@ -33,6 +47,8 @@ module RTP
 
     # Returns self.
     #
+    # @return [Record] self
+    #
     def to_record
       self
     end

data/lib/rtp-connect/ruby_extensions.rb

@@ -1,82 +1,91 @@
-# encoding: UTF-8
-
-# This file contains extensions to the Ruby library which are used by the RTPConnect library.
-
-# Extension to the String class. These extensions are focused on analyzing RTPConnect strings.
-#
-class String
-
-  # Returns the CRC checksum (16 bit unsigned integer) for a given string.
-  #
-  def checksum
-    crc = RTP::CRC_SEED
-    self.each_codepoint do |byte|
-      crc = RTP::CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >> 8)
-    end
-    return crc
-  end
-
-  # Returns the elements of a line from the RTPConnect ascii string.
-  # The line consists of elements (surrounded by double quotes), separated by comma.
-  # This method performs a split based on comma and returns the element strings in an array.
-  #
-  def elements
-    return self.split(',')
-  end
-
-  # Removes double quotes from a string.
-  # Returns the quote-less string.
-  #
-  def value
-    return self.gsub('"', '')
-  end
-
-  # Returns the element values of a line from the RTPConnect ascii string.
-  # The line consists of values (surrounded by double quotes), separated by comma.
-  # This method performs a split based on comma and removes the quotes from each value,
-  # and the resulting quote-less value strings are returned in an array.
-  #
-  def values
-    original = CSV.parse(self).first
-    processed = Array.new
-    original.collect {|element| processed << element.gsub('"', '')}
-    return processed
-  end
-
-  # Wraps double quotes around the string.
-  #
-  def wrap
-    return '"' + self + '"'
-  end
-
-end
-
-
-# Extension to the Array class. These extensions are focused on creating RTPConnect
-# strings from an array of values.
-#
-class Array
-
-  # Encodes an RTPConnect string from an array of values.
-  # Each value in the array is wrapped with double quotes,
-  # before the values are joined with a comma separator.
-  #
-  def encode
-    wrapped = self.collect{|value| value.wrap}
-    return wrapped.join(',')
-  end
-
-end
-
-# An extension to the NilClass, facilitating a transformation from nil to
-# an empty (double quoted) string in the case of undefined attributes.
-#
-class NilClass
-
-  # Returns a double quoted, but otherwise empty string.
-  #
-  def wrap
-    return '""'
-  end
-
+# encoding: UTF-8
+
+# This file contains extensions to the Ruby library which are used by the RTPConnect library.
+
+# Extension to the String class. These facilitate processing and analysis of RTPConnect strings.
+#
+class String
+
+  # Determines the checksum (CRC) for a given string.
+  #
+  # @return [Fixnum] the checksum (a 16 bit unsigned integer)
+  #
+  def checksum
+    crc = RTP::CRC_SEED
+    self.each_codepoint do |byte|
+      crc = RTP::CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >> 8)
+    end
+    return crc
+  end
+
+  # Splits the elements of a string separated by comma.
+  #
+  # @return [Array<String>] an array of the string values originally separated by a comma
+  #
+  def elements
+    self.split(',')
+  end
+
+  # Removes double quotes from a string.
+  #
+  # @return [String] the string stripped of double-quotes
+  #
+  def value
+    self.gsub('"', '')
+  end
+
+  # Splits the elements of a CSV string (comma separated values),
+  # and removes double-quotes from the resulting string elements.
+  #
+  # @return [Array<String>] an array of the comma separated values
+  #
+  def values
+    original = CSV.parse(self).first
+    processed = Array.new
+    original.collect {|element| processed << element.gsub('"', '')}
+    return processed
+  end
+
+  # Wraps double quotes around the string.
+  #
+  # @return [String] the string padded with double-quotes
+  #
+  def wrap
+    '"' + self + '"'
+  end
+
+end
+
+
+# Extension to the Array class. These facilitate the creation
+# of RTPConnect strings from an array of values.
+#
+class Array
+
+  # Encodes an RTPConnect string from an array of values.
+  # Each value in the array is wrapped with double quotes,
+  # before the values are joined with a comma separator.
+  #
+  # @return [String] a proper RTPConnect type CSV string
+  #
+  def encode
+    wrapped = self.collect{|value| value.wrap}
+    return wrapped.join(',')
+  end
+
+end
+
+# An extension to the NilClass, facilitating a transformation from nil to
+# an empty (double quoted) string in the case of undefined attributes.
+#
+class NilClass
+
+  # Gives a double quoted, but otherwise empty string.
+  #
+  # @return [String] a string containing two double-quotes
+  #
+  def wrap
+    '""'
+  end
+
 end