physical 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27de598d29f3754f4a2f4676208da48ba8d83b4e59662c5bd267dffb3ccdee58
-  data.tar.gz: 38cc5da575f4e56cf001370aaea5fd906b82373f75fa6880d804fa20e1b828b9
+  metadata.gz: 6ff0a2d8dd4662fd4642901ea536db815d6d51f318a2f6d8a66da1d32e5f7555
+  data.tar.gz: 991d0b406e3cadd1188fff3d84205467d9e47e93e81bfe4d3b6aa9db32e5f9a5
 SHA512:
-  metadata.gz: 9f80884f5e7333d29be10b70e27e683865e0a0ac1f43cfbb464d13008a482ea57932ccbd963599f3412563b556d535de54c43ab21ffb7b8ad0bac2d859895e26
-  data.tar.gz: abfb28ea0aa1fa6fdcfb8e4b31e7b5412d743a45edc4c22cd71d1b8146cdac741b5da69f362a573ac34985628e208e92c8c442a7de7aaf4e615f4ea6398e404e
+  metadata.gz: 15b3404acebb3c0d24d396cbcb66205c0d457148c5a1a5b08e2bf920a35d7e8e1edddf246707772337e08dc75c448dd3ec0bac0d49aeda26ef6a3a5ea07f92d2
+  data.tar.gz: 30e61b6929b17288830eee2e68967970895807c3d8695f189dd52fb31c783925245d2b6733d1e785fdef8800a1265fd9b316b1f23005e13c55d6bf59d6157056

data/.yardopts

@@ -0,0 +1,9 @@
+--protected
+--no-private
+--readme README.md
+--markup markdown
+--exclude test_support
+--exclude measured/density
+--exclude physical/types
+--exclude physical/property_readers
+'lib/**/*.rb' - '*.md'

data/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [0.6.0] - 2025-08-14
+
+### Changed
+- Require Ruby >= 3.0
+- Upgrade `measured` dependency to `~> 3.0` (bundled as 3.2.1)
+
 ## [0.5.1] - 2023-12-19
 
 ### Changed

data/README.md

@@ -1,20 +1,38 @@
 # Physical
 
-This is a small library to describe Packages (that could, potentially, be mailed).
+This is a small library to describe packages (that could, potentially, be mailed) and
+structures that store packages.
 
-A `Physical::Package` represents a package. It has and ID, dimensions, and a weight.
+### Packages
 
-The `Package` takes it's dimensions from its `container` object, usually a `Physical::Box`.
-It also has a `Set` of `Physical::Item`s that together make with the container make up everything
-about the Package.
+A `Physical::Package` represents a package. It has an ID, dimensions, and weight.
 
-All things are thought to be cuboid: They have three dimensions, and a weight.
+The `Package` takes its dimensions from its `container` object, usually a `Physical::Box`.
+It also has a `Set` of `Physical::Item`s that together with the container make up everything
+about the package.
 
-The weight of a `Package` is the weight of it's container plus the weight of all items, plus the weight
-of any void fill.
+All containers are thought to be `Cuboid`: they have three dimensions and a weight.
 
-By default, the `Physical::Box` is infinitely large. In order to limit the size of the Box, simply give it
-dimensions.
+The weight of a `Package` is the weight of its container plus the weight of all items plus
+the weight of any void fill.
+
+By default, the `Physical::Box` container is infinitely large. In order to limit the size
+of the container, simply give it dimensions.
+
+### Structures
+
+A `Physical::Structure` represents a pallet, skid, rack, or some other collection of packages.
+Similar to a `Package`, it has an ID, dimensions, and weight.
+
+The `Structure` takes its dimensions from its `container` object, usually a `Physical::Pallet`.
+It also has an `Array` of `Physical::Package`s that together with the container make up
+everything about the structure.
+
+The weight of a `Structure` is the weight of its container plus the weight of all packages.
+Structures do not have void fill.
+
+By default, the `Physical::Pallet` container is infinitely large. In order to limit the size
+of the container, simply give it dimensions.
 
 ## Installation
 
@@ -34,9 +52,11 @@ Or install it yourself as:
 
 ## Usage
 
-### Basic Package
+### Basic package
 
-A basic Package has no items and is simply assigned a weight and dimensions. Weights and Dimensions have to be given as `Measured::Weight` or as an Array of `Measured::Length` objects:
+A basic package has no items and is simply assigned a weight and dimensions. Weights must
+be specified as `Measured::Weight` objects. Dimensions must be specified as an array of
+`Measured::Length` objects.
 
 ```ruby
 Physical::Package.new(
@@ -48,29 +68,34 @@ Physical::Package.new(
   ]
 )
 ```
-You will be able to retrieve the package's weight and dimensions using the `#weight` and `#dimensions` attribute reader methods.
-
-### Convenience methods
+The package's weight and dimensions are retrieved using the `#weight` and `#dimensions`
+attribute reader methods.
 
-The length, width and height of a package are defined as the dimension array's first, second, and third argument, respectively. For the package from the previous example, `package.length` will be 3 inches, `package.width` will be 4 inches, and `package.height` will be 5 inches.
+### Package dimensions
 
-### Packages with Items
+The length, width and height of a package are defined as the dimension array's first,
+second, and third argument, respectively. For the package from the previous example,
+`#length` will be 3 inches, `#width` will be 4 inches, and `#height` will be 5 inches.
 
-The following example is a somewhat more elaborate package: We know the items inside! `Physical::Item` objects are Cuboids, so they have three dimensions and a weight. They also have a `properties` hash that can hold things like any hazardous properties that might impede shipping.
+### Packages with items
 
+The following example is a somewhat more elaborate package: we know the items inside!
+`Physical::Item` objects are `Cuboid`, so they have three dimensions and a weight. They also
+have a `properties` hash that can hold things like any hazardous properties that might
+impede shipping.
 
 ```ruby
-sku_one = Physical::Item.new(
+item_one = Physical::Item.new(
   id: '12345',
   dimensions: [
     Measured::Length(2, :inch),
     Measured::Length(4, :inch),
     Measured::Length(5, :inch)
   ],
-  weight: Measured::Weight(1, :kg),
+  weight: Measured::Weight(5, :g),
 )
 
-sku_two = Physical::Item.new(
+item_two = Physical::Item.new(
   id: "54321",
   dimensions: [
     Measured::Length(1, :cm),
@@ -85,18 +110,22 @@ You can initialize a package with items as follows:
 
 ```ruby
 package_with_items = Physical::Package.new(
-  items: [sku_one, sku_two]
+  items: [item_one, item_two]
 )
 ```
 
-This package has no defined container. This means we assume a box that is infinitely large, and that has zero weight. Thus the weight of this `package_with_items` will be 1023 gram (1 kg + 23 g = 1000 g + 23 g).
+This package has no defined container. This means we assume a box that is infinitely large, and
+that has zero weight. Thus the weight of this `package_with_items` will be 28 grams
+(5 g + 23 g = 28 g).
 
-### Packages with Boxes
+### Packages with boxes
 
-A package also has a box that wraps it. This box is assumed to be a Cuboid, too - but one that has inner dimensions, and a weight that is it's own weight which must be added to any item's weight in order to find out the total weight of a package.
+A package also has a container that wraps it. This container is assumed to be a `Cuboid`, too -
+but one that has inner dimensions, and a weight that is it's own weight which must be added to
+item weights in order to find out the total weight of a package.
 
 ```ruby
-my_carton = Physical::Box.new(
+container = Physical::Box.new(
   dimensions: [
     Measured::Length(10, :cm),
     Measured::Length(15, :cm),
@@ -111,22 +140,29 @@ my_carton = Physical::Box.new(
 )
 ```
 
-If you create a carton and omit the inner dimensions, we will assume that the carton's inner dimensions are equal to its outer dimensions. This will, in many cases, be good enough (but in some you'll need the extra precision).
+If you create a container and omit the inner dimensions, we will assume that the container's inner
+dimensions are equal to its outer dimensions. This will, in many cases, be good enough (but in some
+cases you'll need the extra precision).
 
-### Calculating Void Fill
+### Calculating void fill
 
-For an elaborate package with a container box and items, we still cannot find out the full weight of the package without taking into account void fill (styrofoam, bubble wrap or crumpled newspaper maybe). We can instruct the package to fill up all the volume not used up by items with void fill. You can pass the density as a `Measured::Weight` object that refers to the weight of 1 cubic centimeter of void fill:
+For an elaborate package with a container box and items, we still cannot find out the full weight
+of the package  without taking into account void fill (styrofoam, bubble wrap or crumpled newspaper
+maybe). We can instruct the  package to fill up all the volume not used up by items with void fill.
+You can pass the density as a `Measured::Weight` object that refers to the weight of 1 cubic
+centimeter of void fill:
 
 ```ruby
 package = Physical::Package.new(
   id: "my_package",
-  container: my_carton,
-  items: [sku_one, sku_two],
+  container: container,
+  items: [item_one, item_two],
   void_fill_density: Measured::Weight(0.007, :g)
 )
 ```
 
-In this case, the package's weight will be slightly above the sum of carton weight and the sum of item weights, as we incorporate the approximate weight of the void fill material:
+In this case, the package's weight will be slightly above the sum of container weight and the
+sum  of item weights, as we incorporate the approximate weight of the void fill material:
 
 ```ruby
 package.weight
@@ -135,15 +171,115 @@ package.weight
 package.remaining_volume
 => #<Measured::Volume: 1107.51744 #<Measured::Unit: ml (milliliter, millilitre, milliliters, millilitres) 1/1000 l>>
 ```
+### Basic structure
+
+A basic structure has no packages and is simply assigned a weight and dimensions. Weights must
+be specified as `Measured::Weight` objects. Dimensions must be specified as an array of
+`Measured::Length` objects.
+
+```ruby
+Physical::Structure.new(
+  weight: Measured::Weight(1, :pound),
+  dimensions: [
+    Measured::Length(48, :inch),
+    Measured::Length(48, :inch),
+    Measured::Length(96, :inch)
+  ]
+)
+```
+The structure's weight and dimensions are retrieved using the `#weight` and `#dimensions`
+attribute reader methods.
+
+### Structure dimensions
+
+The length, width and height of a structure are defined as the dimension array's first,
+second, and third argument, respectively. For the structure from the previous example,
+`#length` will be 48 inches, `#width` will be 48 inches, and `#height` will be 96 inches
+(the approximate dimensions of a pallet).
+
+### Structures with packages
+
+The following example is a somewhat more elaborate structure: we know the packages inside!
+`Physical::Package` objects are `Cuboid`, so they have three dimensions and a weight. They also
+have a `properties` hash that can hold things like any hazardous properties that might
+impede shipping.
+
+```ruby
+package_one = Physical::Package.new(
+  id: '12345',
+  dimensions: [
+    Measured::Length(2, :inch),
+    Measured::Length(4, :inch),
+    Measured::Length(5, :inch)
+  ],
+  weight: Measured::Weight(1, :kg),
+)
+
+package_two = Physical::Package.new(
+  id: "54321",
+  dimensions: [
+    Measured::Length(1, :cm),
+    Measured::Length(1, :cm),
+    Measured::Length(1, :cm)
+  ],
+  weight: Measured::Weight(23, :g)
+)
+```
+
+You can initialize a structure with packages as follows:
+
+```ruby
+structure_with_packages = Physical::Structure.new(
+  items: [package_one, package_two]
+)
+```
+
+This structure has no defined container. This means we assume a pallet that is infinitely large,
+and that has zero weight. Thus the weight of this `structure_with_packages` will be 1023 grams
+(1 kg + 73 g = 1000 g + 23 g = 1023 g).
+
+### Structures with pallets
+
+A structure also has a container that wraps it. This container is assumed to be a `Cuboid`, too -
+but one that has inner dimensions, and a weight that is it's own weight which must be added to
+package weights in order to find out the total weight of a structure.
+
+```ruby
+container = Physical::Pallet.new(
+  dimensions: [
+    Measured::Length(10, :cm),
+    Measured::Length(15, :cm),
+    Measured::Length(15, :cm)
+  ],
+  inner_dimensions: [
+    Measured::Length(9, :cm),
+    Measured::Length(14, :cm),
+    Measured::Length(14, :cm)
+  ],
+  weight: Measured::Weight(350, :g),
+)
+```
+
+If you create a container and omit the inner dimensions, we will assume that the container's inner
+dimensions are equal to its outer dimensions. This will, in many cases, be good enough (but in some
+cases you'll need the extra precision).
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to
+run the tests. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version, push git commits and tags, and push the `.gem`
+file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/friendlycart/physical. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/friendlycart/physical.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are
+expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -151,4 +287,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Physical project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/physical/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Physical project’s codebases, issue trackers, chat rooms and
+mailing lists is expected to follow the [code of conduct](https://github.com/friendlycart/physical/blob/main/CODE_OF_CONDUCT.md).

data/lib/physical/box.rb

@@ -3,25 +3,52 @@
 require 'measured'
 
 module Physical
+  # Represents a physical box which items can be packed into.
   class Box < Cuboid
+    # The default dimensions of this box when unspecified
     DEFAULT_LENGTH = BigDecimal::INFINITY
+
+    # The default maximum weight of this box when unspecified
     DEFAULT_MAX_WEIGHT = BigDecimal::INFINITY
 
-    attr_reader :inner_dimensions,
-                :inner_length,
-                :inner_width,
-                :inner_height,
-                :max_weight
+    # The inner length, width, and height of this box
+    # @return [Array<Measured::Length>]
+    attr_reader :inner_dimensions
+
+    # The inner length of this box
+    # @return [Measured::Length]
+    attr_reader :inner_length
+
+    # The inner width of this box
+    # @return [Measured::Length]
+    attr_reader :inner_width
+
+    # The inner height of this box
+    # @return [Measured::Length]
+    attr_reader :inner_height
+
+    # The maximum weight this box can handle
+    # @return [Measured::Weight]
+    attr_reader :max_weight
 
-    def initialize(**args)
-      inner_dimensions = args.delete(:inner_dimensions) || []
-      max_weight = args.delete(:max_weight) || Measured::Weight(DEFAULT_MAX_WEIGHT, :g)
-      super(**args)
+    # @param [Hash] kwargs ID, dimensions, weight, and properties
+    # @option kwargs [String] :id a unique identifier for this box
+    # @option kwargs [Array<Measured::Length>] :dimensions the outer length, width, and height of this box
+    # @option kwargs [Array<Measured::Length>] :inner_dimensions the inner length, width, and height of this box
+    # @option kwargs [Measured::Weight] :weight the weight of the box itself (excluding what's inside)
+    # @option kwargs [Measured::Weight] :max_weight the maximum weight this box can handle
+    # @option kwargs [Hash] :properties additional custom properties for this box
+    def initialize(**kwargs)
+      inner_dimensions = kwargs.delete(:inner_dimensions) || []
+      max_weight = kwargs.delete(:max_weight) || Measured::Weight(DEFAULT_MAX_WEIGHT, :g)
+      super(**kwargs)
       @inner_dimensions = fill_dimensions(Types::Dimensions[inner_dimensions])
       @inner_length, @inner_width, @inner_height = *@inner_dimensions
       @max_weight = Types::Weight[max_weight]
     end
 
+    # Calculates and returns this box's volume based on the inner dimensions
+    # @return [Measured::Volume]
     def inner_volume
       Measured::Volume(
         inner_dimensions.map { |d| d.convert_to(:cm).value }.reduce(1, &:*),
@@ -29,6 +56,7 @@ module Physical
       )
     end
 
+    # Returns true if the given item can fit inside this box
     # @param [Physical::Item] item
     # @return [Boolean]
     def item_fits?(item)

data/lib/physical/cuboid.rb

@@ -3,11 +3,42 @@
 require 'measured'
 
 module Physical
+  # Represents a cube-shaped physical object with dimensions and weight.
   class Cuboid
     include PropertyReaders
 
-    attr_reader :dimensions, :length, :width, :height, :weight, :id, :properties
+    # A unique identifier for this cuboid
+    # @return [String]
+    attr_reader :id
 
+    # The length, width, and height of this cuboid
+    # @return [Array<Measured::Length>]
+    attr_reader :dimensions
+
+    # The length of this cuboid
+    # @return <Measured::Length>
+    attr_reader :length
+
+    # The width of this cuboid
+    # @return <Measured::Length>
+    attr_reader :width
+
+    # The height of this cuboid
+    # @return <Measured::Length>
+    attr_reader :height
+
+    # The weight of the cuboid itself (excluding what's inside)
+    # @return [Measured::Weight]
+    attr_reader :weight
+
+    # Additional custom properties for this cuboid
+    # @return [Hash]
+    attr_reader :properties
+
+    # @param [String] id a unique identifier for this cuboid
+    # @param [Array<Measured::Length>] dimensions the length, width, and height of this cuboid
+    # @param [Measured::Weight] weight the weight of the cuboid itself (excluding what's inside)
+    # @param [Hash] properties additional custom properties for this cuboid
     def initialize(id: nil, dimensions: [], weight: Measured::Weight(0, :g), properties: {})
       @id = id || SecureRandom.uuid
       @weight = Types::Weight[weight]
@@ -17,10 +48,14 @@ module Physical
       @properties = properties
     end
 
+    # Calculates and returns this cuboid's volume based on its dimensions.
+    # @return [Measured::Volume]
     def volume
       Measured::Volume(dimensions.map { |d| d.convert_to(:cm).value }.reduce(1, &:*), :ml)
     end
 
+    # Calculates and returns this cuboid's density based on its volume and weight.
+    # @return [Measured::Density]
     def density
       return Measured::Density(Float::INFINITY, :g_ml) if volume.value.zero?
       return Measured::Density(0.0, :g_ml) if volume.value.infinite?
@@ -28,6 +63,9 @@ module Physical
       Measured::Density(weight.convert_to(:g).value / volume.convert_to(:ml).value, :g_ml)
     end
 
+    # Returns true if the given object shares the same class and ID with this cuboid.
+    # @param [Object] other
+    # @return [Boolean]
     def ==(other)
       other.is_a?(self.class) &&
         id == other&.id
@@ -35,6 +73,9 @@ module Physical
 
     private
 
+    # Fills an array with dimensions or with default values if unspecified.
+    # @param [Array<Measured::Length>] dimensions
+    # @return [Array<Measured::Length>]
     def fill_dimensions(dimensions)
       dimensions.fill(dimensions.length..2) do |index|
         @dimensions[index] || Measured::Length(self.class::DEFAULT_LENGTH, :cm)

data/lib/physical/item.rb

@@ -1,13 +1,31 @@
 # frozen_string_literal: true
 
 module Physical
+  # Represents a physical item which can be packed into a box.
   class Item < Cuboid
+    # The default dimensions of this item when unspecified
     DEFAULT_LENGTH = 0
 
-    attr_reader :cost,
-                :sku,
-                :description
+    # The cost for this item
+    # @return [Money]
+    attr_reader :cost
 
+    # The SKU for this item
+    # @return [String]
+    attr_reader :sku
+
+    # A description for this item
+    # @return [String]
+    attr_reader :description
+
+    # @param [Hash] kwargs ID, dimensions, weight, and properties
+    # @option kwargs [String] :id a unique identifier for this item
+    # @option kwargs [Money] :cost the cost of this item
+    # @option kwargs [String] :sku the SKU for this item
+    # @option kwargs [String] :description a description for this item
+    # @option kwargs [Array<Measured::Length>] :dimensions the length, width, and height of this item
+    # @option kwargs [Measured::Weight] :weight the weight of this item
+    # @option kwargs [Hash] :properties additional custom properties for this item
     def initialize(**kwargs)
       @cost = Types::Money.optional[kwargs.delete(:cost)]
       @sku = kwargs.delete(:sku)

data/lib/physical/location.rb

@@ -3,28 +3,93 @@
 require 'carmen'
 
 module Physical
+  # Represents a physical location.
   class Location
     include PropertyReaders
 
+    # Possible address types for this location
     ADDRESS_TYPES = %w(residential commercial po_box).freeze
 
-    attr_reader :country,
-                :zip,
-                :region,
-                :city,
-                :name,
-                :address1,
-                :address2,
-                :address3,
-                :phone,
-                :fax,
-                :email,
-                :address_type,
-                :company_name,
-                :latitude,
-                :longitude,
-                :properties
+    # This location's country
+    # @return [Carmen::Country]
+    attr_reader :country
 
+    # This location's postal code
+    # @return [String]
+    attr_reader :zip
+
+    # This location's state or province
+    # @return [Carmen::Region]
+    attr_reader :region
+
+    # This location's city
+    # @return [String]
+    attr_reader :city
+
+    # This location's name (could be a person's name)
+    # @return [String]
+    attr_reader :name
+
+    # This location's address line 1
+    # @return [String]
+    attr_reader :address1
+
+    # This location's address line 2
+    # @return [String]
+    attr_reader :address2
+
+    # This location's address line 3
+    # @return [String]
+    attr_reader :address3
+
+    # This location's phone
+    # @return [String]
+    attr_reader :phone
+
+    # This location's fax
+    # @return [String]
+    attr_reader :fax
+
+    # This location's email
+    # @return [String]
+    attr_reader :email
+
+    # This location's address type (see {ADDRESS_TYPES})
+    # @return [String]
+    attr_reader :address_type
+
+    # This location's company name
+    # @return [String]
+    attr_reader :company_name
+
+    # This location's latitude
+    # @return [String]
+    attr_reader :latitude
+
+    # This location's longitude
+    # @return [String]
+    attr_reader :longitude
+
+    # Additional custom properties for this location
+    # @return [String]
+    attr_reader :properties
+
+    # @param [String] name the name of this location (could be a person's name)
+    # @param [String] company_name the name of the company at this location
+    # @param [String] address1 the first line of the address
+    # @param [String] address2 the second line of the address
+    # @param [String] address3 the third line of the address
+    # @param [String] city the city
+    # @param [String, Carmen::Region] region the state or province
+    # @param [String] zip the postal code
+    # @param [String, Carmen::Country] country the country
+    # @param [String] phone the phone number
+    # @param [String] fax the fax number
+    # @param [String] email the email address
+    # @param [String] address_type the type of address (see {ADDRESS_TYPES})
+    # @param [String] latitude the latitude at this location
+    # @param [String] longitude the longitude at this location
+    # @param [Hash] properties additional custom properties for this location
     def initialize(
       name: nil,
       company_name: nil,
@@ -72,18 +137,26 @@ module Physical
       @properties = properties
     end
 
+    # Returns true if this location's address type is "residential"
+    # @return [Boolean]
     def residential?
       @address_type == 'residential'
     end
 
+    # Returns true if this location's address type is "commercial"
+    # @return [Boolean]
     def commercial?
       @address_type == 'commercial'
     end
 
+    # Returns true if this location's address type is "po_box"
+    # @return [Boolean]
     def po_box?
       @address_type == 'po_box'
     end
 
+    # Returns a hash representation of this location.
+    # @return [Hash]
     def to_hash
       {
         country: country&.code,
@@ -102,6 +175,8 @@ module Physical
       }
     end
 
+    # Returns true if the given object's class and {#to_hash} match this location.
+    # @return [Boolean]
     def ==(other)
       other.is_a?(self.class) &&
         to_hash == other&.to_hash

data/lib/physical/package.rb

@@ -1,10 +1,46 @@
 # frozen_string_literal: true
 
 module Physical
+  # Represents a physical package which has a container (box) and items.
   class Package
     extend Forwardable
-    attr_reader :id, :container, :items, :void_fill_density, :items_weight, :used_volume, :description
 
+    # A unique identifier for this package
+    # @return [String]
+    attr_reader :id
+
+    # The container ({Box}) for this package
+    # @return [Physical::Cuboid]
+    attr_reader :container
+
+    # The items contained by this package
+    # @return [Array<Physical::Item>]
+    attr_reader :items
+
+    # The density of the void fill in this package
+    # @return [Measured::Density]
+    attr_reader :void_fill_density
+
+    # The weight of the items in this package
+    # @return [Measured::Weight]
+    attr_reader :items_weight
+
+    # The total volume used by the items in this package
+    # @return [Measured::Volume]
+    attr_reader :used_volume
+
+    # The description for this package
+    # @return [String]
+    attr_reader :description
+
+    # @param [String] id a unique identifier for this package
+    # @param [Physical::Cuboid] container the container ({Box}) for this package
+    # @param [Array<Physical::Item>] items the items contained by this package
+    # @param [Measured::Density] void_fill_density the density of the void fill in this package
+    # @param [Array<Measured::Length>] dimensions the length, width, and height of this package's container
+    # @param [Measured::Weight] weight the weight of this package's container
+    # @param [String] description a description for this package
+    # @param [Hash] properties additional custom properties for this package's container
     def initialize(id: nil, container: nil, items: [], void_fill_density: Measured::Density(0, :g_ml), dimensions: nil, weight: nil, description: nil, properties: {})
       @id = id || SecureRandom.uuid
       @void_fill_density = Types::Density[void_fill_density]
@@ -16,8 +52,22 @@ module Physical
       @used_volume = @items.map(&:volume).reduce(Measured::Volume(0, :ml), &:+)
     end
 
+    # @!attribute [r] dimensions
+    #   The container's dimensions
+    # @!attribute [r] weight
+    #   The container's weight
+    # @!attribute [r] length
+    #   The container's length
+    # @!attribute [r] height
+    #   The container's height
+    # @!attribute [r] properties
+    #   The container's additional custom properties
+    # @!attribute [r] volume
+    #   The container's volume
     delegate [:dimensions, :width, :length, :height, :properties, :volume] => :container
 
+    # Adds an item to the package.
+    # @param [Physical::Item] other the item to add
     def <<(other)
       @items.add(other)
       @items_weight += other.weight
@@ -25,6 +75,8 @@ module Physical
     end
     alias_method :add, :<<
 
+    # Removes an item from the package.
+    # @param [Physical::Item] other the item to remove
     def >>(other)
       @items.delete(other)
       @items_weight -= other.weight
@@ -32,28 +84,37 @@ module Physical
     end
     alias_method :delete, :>>
 
+    # Sums container weight, items weight, and void fill weight and returns the total.
+    # @return [Measured::Weight]
     def weight
       container.weight + items_weight + void_fill_weight
     end
 
-    # Cost is optional. We will only return an aggregate if all items
-    # have cost defined. Otherwise we will return nil.
-    # @return Money
+    # Sums and returns the cost from all items in this package. Item cost is
+    # optional, therefore we only return a sum if *all* items have a cost.
+    # Otherwise, nil is returned.
+    # @return [Money, nil]
     def items_value
       items_cost = items.map(&:cost)
       items_cost.reduce(&:+) if items_cost.compact.size == items_cost.size
     end
 
+    # Calculates and returns the weight of the void fill in this package.
+    # @return [Measured::Weight]
     def void_fill_weight
       return Measured::Weight(0, :g) if container.volume.value.infinite?
 
       Measured::Weight(void_fill_density.convert_to(:g_ml).value * remaining_volume.convert_to(:ml).value, :g)
     end
 
+    # Calculates and returns remaining volume in this package.
+    # @return [Measured::Volume]
     def remaining_volume
       container.inner_volume - used_volume
     end
 
+    # Returns the density of this package based on its volume and weight.
+    # @return [Measured::Density]
     def density
       return Measured::Density(Float::INFINITY, :g_ml) if container.volume.value.zero?
       return Measured::Density(0.0, :g_ml) if container.volume.value.infinite?

data/lib/physical/pallet.rb

@@ -3,24 +3,52 @@
 require 'measured'
 
 module Physical
+  # Represents a physical pallet which holds boxes.
   class Pallet < Cuboid
+    # The default dimensions of this pallet when unspecified
     DEFAULT_LENGTH = BigDecimal::INFINITY
+
+    # The default maximum weight of this pallet when unspecified
     DEFAULT_MAX_WEIGHT = BigDecimal::INFINITY
 
+    # The maximum weight this pallet can handle
+    # @return [Measured::Weight]
     attr_reader :max_weight
 
-    def initialize(**args)
-      max_weight = args.delete(:max_weight) || Measured::Weight(DEFAULT_MAX_WEIGHT, :g)
-      super(**args)
+    # @param [Hash] kwargs ID, dimensions, weight, and properties
+    # @option kwargs [String] :id a unique identifier for this pallet
+    # @option kwargs [Array<Measured::Length>] :dimensions the length, width, and height of this pallet
+    # @option kwargs [Measured::Weight] :weight the weight of the pallet itself (excluding what's on top)
+    # @option kwargs [Measured::Weight] :max_weight the maximum weight this pallet can handle
+    # @option kwargs [Hash] :properties additional custom properties for this pallet
+    def initialize(**kwargs)
+      max_weight = kwargs.delete(:max_weight) || Measured::Weight(DEFAULT_MAX_WEIGHT, :g)
+      super(**kwargs)
       @max_weight = Types::Weight[max_weight]
     end
 
+    # @!method volume
+    #   @return [Measured::Volume] the volume of this pallet
     alias_method :inner_volume, :volume
+
+    # @!method dimensions
+    #   @return [Array<Measured::Length>] the dimensions of this pallet
     alias_method :inner_dimensions, :dimensions
+
+    # @!method length
+    #   @return [Measured::Length] the length of this pallet
     alias_method :inner_length, :length
+
+    # @!method width
+    #   @return [Measured::Length] the width of this pallet
     alias_method :inner_width, :width
+
+    # @!method height
+    #   @return [Measured::Length] the height of this pallet
     alias_method :inner_height, :height
 
+    # Returns true if the given package can fit on the pallet. Checks package
+    # dimensions and weight against pallet dimensions and max weight.
     # @param [Physical::Package] package
     # @return [Boolean]
     def package_fits?(package)

data/lib/physical/shipment.rb

@@ -1,16 +1,48 @@
 # frozen_string_literal: true
 
 module Physical
+  # Represents a physical shipment containing structures and/or packages.
   class Shipment
-    attr_reader :id,
-                :origin,
-                :destination,
-                :service_code,
-                :pallets,
-                :structures,
-                :packages,
-                :options
+    # A unique identifier for this shipment
+    # @return [String]
+    attr_reader :id
 
+    # This shipment's origin location
+    # @return [Physical::Location]
+    attr_reader :origin
+
+    # This shipment's destination location
+    # @return [Physical::Location]
+    attr_reader :destination
+
+    # The shipment carrier's service code
+    # @return [String]
+    attr_reader :service_code
+
+    # This shipment's pallets (DEPRECATED: use {#structures} instead)
+    # @return [Array<Physical::Pallet>]
+    attr_reader :pallets
+
+    # This shipment's structures (pallets, skids, etc.) which hold packages
+    # @return [Array<Physical::Structure>]
+    attr_reader :structures
+
+    # This shipment's packages which hold items
+    # @return [Array<Physical::Package>]
+    attr_reader :packages
+
+    # Additional custom options for this shipment
+    # @return [Hash]
+    attr_reader :options
+
+    # @param [String] id a unique identifier for this shipment
+    # @param [Physical::Location] origin the shipment's origin location
+    # @param [Physical::Location] destination the shipment's destination location
+    # @param [String] service_code the shipment carrier's service code
+    # @param [Array<Physical::Pallet>] pallets the shipment's pallets (DEPRECATED: use `structures` instead)
+    # @param [Array<Physical::Structure>] structures the shipment's structures (pallets, skids, etc.) which hold packages
+    # @param [Array<Physical::Package>] packages the shipment's packages (boxes) which hold items
+    # @param [Hash] options additional custom options for this shipment
     def initialize(id: nil, origin: nil, destination: nil, service_code: nil, pallets: [], structures: [], packages: [], options: {})
       @id = id || SecureRandom.uuid
       @origin = origin

data/lib/physical/structure.rb

@@ -1,10 +1,36 @@
 # frozen_string_literal: true
 
 module Physical
+  # Represents a physical structure which has a container (pallet, skid, etc.) and packages.
   class Structure
     extend Forwardable
-    attr_reader :id, :container, :packages, :packages_weight, :used_volume
 
+    # A unique identifier for this structure
+    # @return [String]
+    attr_reader :id
+
+    # The container ({Pallet}) for this structure
+    # @return [Physical::Cuboid]
+    attr_reader :container
+
+    # The packages contained by this structure
+    # @return [Array<Physical::Package>]
+    attr_reader :packages
+
+    # The weight of the packages in this structure
+    # @return [Measured::Weight]
+    attr_reader :packages_weight
+
+    # The total volume used by the packages in this structure
+    # @return [Measured::Volume]
+    attr_reader :used_volume
+
+    # @param [String] id a unique identifier for this structure
+    # @param [Physical::Cuboid] container the container ({Pallet}) for this structure
+    # @param [Array<Physical::Package>] packages the packages contained by this structure
+    # @param [Array<Measured::Length>] dimensions the length, width, and height of this structure's container
+    # @param [Measured::Weight] weight the weight of this structure's container
+    # @param [Hash] properties additional custom properties for this package's container
     def initialize(id: nil, container: nil, packages: [], dimensions: nil, weight: nil, properties: {})
       @id = id || SecureRandom.uuid
       @container = container || Physical::Pallet.new(dimensions: dimensions || [], weight: weight || Measured::Weight(0, :g), properties: properties)
@@ -14,8 +40,22 @@ module Physical
       @used_volume = @packages.map(&:volume).reduce(Measured::Volume(0, :ml), &:+)
     end
 
+    # @!attribute [r] dimensions
+    #   The container's dimensions
+    # @!attribute [r] weight
+    #   The container's weight
+    # @!attribute [r] length
+    #   The container's length
+    # @!attribute [r] height
+    #   The container's height
+    # @!attribute [r] properties
+    #   The container's additional custom properties
+    # @!attribute [r] volume
+    #   The container's volume
     delegate [:dimensions, :width, :length, :height, :properties, :volume] => :container
 
+    # Adds a package to the structure.
+    # @param [Physical::Package] other the package to add
     def <<(other)
       @packages.add(other)
       @packages_weight += other.weight
@@ -23,6 +63,8 @@ module Physical
     end
     alias_method :add, :<<
 
+    # Removes a package from the structure.
+    # @param [Physical::Package] other the package to remove
     def >>(other)
       @packages.delete(other)
       @packages_weight -= other.weight
@@ -30,22 +72,29 @@ module Physical
     end
     alias_method :delete, :>>
 
+    # Sums container weight and packages weight and returns the total.
+    # @return [Measured::Weight]
     def weight
       container.weight + packages_weight
     end
 
-    # Cost is optional. We will only return an aggregate if all packages
-    # have items value defined. Otherwise we will return nil.
-    # @return Money
+    # Sums and returns the item cost from all packages in this structure.
+    # Item cost is optional, therefore we only return a sum if *all* packages
+    # return item cost. Otherwise, nil is returned.
+    # @return [Money, nil]
     def packages_value
       packages_cost = packages.map(&:items_value)
       packages_cost.reduce(&:+) if packages_cost.compact.size == packages_cost.size
     end
 
+    # Calculates and returns remaining volume in this structure.
+    # @return [Measured::Volume]
     def remaining_volume
       container.inner_volume - used_volume
     end
 
+    # Returns the density of this structure based on its volume and weight.
+    # @return [Measured::Density]
     def density
       return Measured::Density(Float::INFINITY, :g_ml) if container.volume.value.zero?
       return Measured::Density(0.0, :g_ml) if container.volume.value.infinite?

data/lib/physical/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Physical
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/physical.gemspec

@@ -19,17 +19,20 @@ Gem::Specification.new do |spec|
     f.match(%r{^(spec)/})
   end
   spec.require_paths = ["lib"]
-  spec.required_ruby_version = '>= 2.4'
+  spec.required_ruby_version = '>= 3.0'
   spec.add_runtime_dependency "carmen", "~> 1.0"
   spec.add_runtime_dependency "dry-types", "~> 1.5"
-  spec.add_runtime_dependency "measured", "~> 2.4"
+  spec.add_runtime_dependency "measured", "~> 3.0"
   spec.add_runtime_dependency "money", ">= 5"
 
   spec.add_development_dependency "bundler", [">= 1.16", "< 3"]
   spec.add_development_dependency "factory_bot", "~> 6.2"
+  spec.add_development_dependency "rack"
   spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec_junit_formatter", "~> 0.4"
   spec.add_development_dependency "rubocop"
   spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "webrick"
+  spec.add_development_dependency "yard"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: physical
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Martin Meyerhoff
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carmen
@@ -44,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: money
   requirement: !ruby/object:Gem::Requirement
@@ -100,6 +99,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -170,6 +183,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A package with boxes and items
 email:
 - mamhoff@gmail.com
@@ -183,6 +224,7 @@ files:
 - ".rubocop-relaxed.yml"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -220,7 +262,6 @@ homepage: https://github.com/friendlycart/physical
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -228,15 +269,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
-signing_key:
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A facade to deal with physical packages
 test_files: []