geopolitical 2.0.0 → 3.2.0

data/app/models/city.rb

@@ -1,86 +1,187 @@
+# frozen_string_literal: true
+
+# Represents a city within a nation and, optionally, a region.
 #
-# Cities
+# Cities have a name, geographical location (`geom`), area, and can be associated
+# with neighborhoods (`Hood`). They also inherit common geopolitical attributes
+# from the `Geopolitocracy` concern (like `name`, `abbr`, `slug`, `pop`, `phone`, `postal`).
 #
+# The city's `slug` is automatically generated and suffixed with its region's
+# abbreviation to ensure uniqueness across regions.
 class City
   include Mongoid::Document
-  include Mongoid::Geospatial
+  include Mongoid::Geospatial # For GIS capabilities like `geom` field and spatial queries
   include Geopolitocracy
 
-  field :area,    type: Integer # m2 square area
+  # @!attribute [rw] area
+  #   @return [Integer] The square area of the city in square meters (m2).
+  field :area,    type: Integer
+  # @!attribute [rw] geom
+  #   @return [Point] The geographical coordinates (longitude, latitude) of the city.
+  #   Indexed for spatial queries.
   field :geom,    type: Point, spatial: true
-  # field :capital, type: String
+  # @!attribute [rw] rbbr
+  #   @return [String] Cached abbreviation of the city's region.
+  #   Used internally, primarily to construct unique slugs.
+  #   Alias: `region_abbr` (writer only, getter is custom).
+  field :rbbr,    type: String, as: :region_abbr
 
+  # Enables spatial queries on the `geom` field.
   spatial_scope :geom
 
-  attr_writer :x, :y, :z
-
+  # @!attribute [rw] region
+  #   @return [Region, nil] The region this city belongs to. Optional.
   belongs_to :region, inverse_of: :cities, optional: true
+  # @!attribute [rw] nation
+  #   @return [Nation] The nation this city belongs to. Required.
   belongs_to :nation, inverse_of: :cities
-  has_many :hoods
-
-  has_one :nation_governancy, as: :nation_capital, class_name: 'Nation'
-  has_one :region_governancy, as: :region_capital, class_name: 'Region'
-
-  before_validation :set_defaults, on: [:create]
-
-  validates :name, uniqueness: { scope: :region_id }
-  validate :region_inside_nation
 
-  scope :population, -> { order_by(souls: -1) }
-
-  index nation_id: 1
-  index souls: -1
-  index name: 1, nation_id: 1
-  index({ region_id: 1 }, sparse: true)
+  # @!attribute [rw] hoods
+  #   @return [Mongoid::Relations::Targets::Enumerable<Hood>] Neighborhoods within this city.
+  has_many :hoods, dependent: :destroy # Assuming hoods should be destroyed if city is
+
+  # @!attribute [r] nation_governancy
+  #   @return [Nation, nil] The nation for which this city is the capital.
+  #   This association signifies that the city is a national capital.
+  has_one :nation_governancy, class_name: 'Nation', inverse_of: :capital, foreign_key: :capital_id
+  # @!attribute [r] region_governancy
+  #   @return [Region, nil] The region for which this city is the capital.
+  #   This association signifies that the city is a regional capital.
+  has_one :region_governancy, class_name: 'Region', inverse_of: :capital, foreign_key: :capital_id
+
+  before_validation :ensure_derived_fields_and_slug
+
+  validates :name, uniqueness: { scope: %i[nation_id region_id], message: 'must be unique within its region' }
+  validates :nation, presence: true
+  validate :region_inside_nation_if_region_present
+
+  # @!method self.population
+  #   @return [Mongoid::Criteria] Cities ordered by population in descending order.
+  scope :population, -> { order_by(souls: :desc) }
+
+  index({ slug: 1 }, unique: true)
+  index({ name: 1, nation_id: 1 }) # For lookups by name within a nation
+  index({ nation_id: 1 })          # For finding all cities in a nation
+  index({ region_id: 1 }, sparse: true) # For finding cities in a region, sparse if region is optional
+  index({ souls: -1 }) # For sorting by population count
+  index({ geom: '2dsphere' }) # Explicit 2dsphere index for geospatial queries
+
+  # Validates that if a city is associated with a region, that region
+  # belongs to the same nation as the city.
+  def region_inside_nation_if_region_present
+    return unless region.present? # Only validate if region is set
+    return if nation.nil? # Avoid error if nation is not yet set (covered by presence validation)
+    return if region.nation == nation
+
+    errors.add(
+      :region,
+      'must be within the same nation as the city. ' \
+      "Region's nation: #{region.nation&.abbr}, City's nation: #{nation.abbr}."
+    )
+  end
 
-  def region_inside_nation
-    return if !region || region.nation == nation
-    errors.add(:region, 'not inside Nation')
+  # Gets the region's abbreviation (`rbbr`).
+  # If `rbbr` is not set and the city has a region, it populates `rbbr`
+  # with the region's abbreviation or name. This value is then cached on the city.
+  #
+  # @return [String, nil] The region's abbreviation or name, or nil if not determinable.
+  def region_abbr
+    current_rbbr = read_attribute(:rbbr)
+    if current_rbbr.blank? && region.present?
+      new_rbbr = region.abbr.presence || region.name.presence
+      write_attribute(:rbbr, new_rbbr) if new_rbbr.present?
+      return new_rbbr
+    end
+    current_rbbr
   end
 
-  def set_defaults
-    self.nation ||= region.try(:nation)
-    return unless City.where(slug: slug).first
-    self.slug += "-#{region.abbr}"
-    return unless City.where(slug: slug).first
-    raise "Two cities with the same name in #{region}: '#{slug}'"
+  # Callback executed before validation to:
+  # 1. Derive the `nation` from the `region` if `nation` is not set and `region` is.
+  # 2. Ensure `rbbr` (region abbreviation) is populated if possible, and refreshed if the city moved.
+  # 3. Append the (lowercase) region abbreviation to the `slug` (generated by `Geopolitocracy`)
+  #    to ensure city slugs are unique, e.g., "cityname-regionabbr" — or the nation
+  #    abbreviation when the city has no region, e.g. "singapore-sg".
+  def ensure_derived_fields_and_slug
+    # 1. Derive nation from region if possible and not already set
+    self.nation = region.nation if region.present? && nation.blank?
+
+    # 2. A moved city gets a fresh abbr cache and a slug rebuilt from its name,
+    #    otherwise the old suffix would stick around ("santos-sp-rj").
+    if persisted? && (region_id_changed? || nation_id_changed?)
+      write_attribute(:rbbr, nil)
+      self.slug = name
+    end
+
+    # 3. Suffix the slug so it is unique planet-wide: the region abbr where there
+    #    is a region ("santos-sp"), the nation abbr otherwise ("singapore-sg").
+    suffix = region_abbr.presence || nation&.abbr
+    return if suffix.blank? || slug.blank?
+
+    slug_suffix = "-#{Geopolitocracy.slugify(suffix)}"
+    self.slug += slug_suffix unless slug.end_with?(slug_suffix)
   end
 
+  # Retrieves the phone number for the city.
+  # Falls back to the region's phone, then the nation's phone if the city's is not set.
+  # Assumes `phone` field is provided by `Geopolitocracy`.
+  #
+  # @return [String, nil] The phone number.
   def phone
-    self[:phone] || region.phone || nation.phone
+    self[:phone] || region&.phone || nation&.phone
   end
 
+  # Collects unique, non-nil phone numbers from all associated hoods.
+  # Assumes `phone` field is provided by `Geopolitocracy` on Hood model.
+  #
+  # @return [Array<String>] An array of unique phone numbers.
   def phones
-    hoods.map(&:phone)
+    hoods.map(&:phone).compact.uniq
   end
 
+  # Retrieves the postal code for the city.
+  # Falls back to the region's postal code, then the nation's if the city's is not set.
+  # Assumes `postal` field is provided by `Geopolitocracy`.
+  #
+  # @return [String, nil] The postal code.
   def postal
-    self[:postal] || region.postal || nation.postal
+    self[:postal] || region&.postal || nation&.postal
   end
 
+  # Collects unique, non-nil postal codes from all associated hoods.
+  # Assumes `postal` field is provided by `Geopolitocracy` on Hood model.
+  #
+  # @return [Array<String>] An array of unique postal codes.
   def postals
-    hoods.map(&:postal)
+    hoods.map(&:postal).compact.uniq
   end
 
-  def ==(other)
-    return unless other.is_a?(City)
-    other && slug == other.slug
-  end
-
-  def <=>(other)
-    return unless other.is_a?(City)
-    slug <=> other.slug
-  end
+  # Returns the city's name, optionally suffixed with its region's abbreviation.
+  #
+  # @param separator [String] The string to use between the name and region abbreviation.
+  # @return [String] The formatted name.
+  def with_region(separator = '/')
+    # Use the getter for region_abbr to ensure it's loaded if available
+    current_region_abbr = region_abbr
+    return name unless current_region_abbr.present?
 
-  def with_region
-    return name unless region
-    "#{name}/#{region.abbr || region.name}"
+    "#{name}#{separator}#{current_region_abbr}"
   end
 
-  def with_nation
-    with_region + '/' + nation.abbr
+  # Returns the city's name, suffixed with its region's and nation's abbreviations.
+  # e.g., "CityName/RegionAbbr/NationAbbr"
+  #
+  # @param separator [String] The string to use as a separator.
+  # @return [String] The formatted name string.
+  def with_nation(separator = '/')
+    base = with_region(separator) # Relies on with_region using the (potentially now loaded) region_abbr
+    # Ensure nation and nation.abbr are present before appending
+    base += "#{separator}#{nation.abbr}" if nation&.abbr.present?
+    base
   end
 
+  # Default string representation of the city.
+  #
+  # @return [String] The city name, possibly with its region abbreviation.
   def to_s
     with_region
   end

data/app/models/concerns/geopolitocracy.rb

@@ -1,61 +1,148 @@
-# Geopolitical Helpers
+# frozen_string_literal: true
+
+#
+# Provides common fields, validations, and helper methods for geopolitical entities
+# like Nations, Regions, Cities, and Hoods.
+#
+# NOTE: A Geonames ID is used as ID
+#
+# It includes fields for names, abbreviations, population, codes, and contact details.
+# It also handles automatic slug generation and provides a basic search functionality.
+#
 module Geopolitocracy
   extend ActiveSupport::Concern
 
+  # Turns any name into a URL-friendly slug: "São Paulo" => "sao-paulo".
+  # Latin script is transliterated to ASCII (accents stripped via NFKD, then
+  # æ/ø/ß/đ via I18n); other scripts (日本, Москва, دبي) keep their letters so
+  # the slug is never blank: "東京" => "東京", "Санкт-Петербург" => "санкт-петербург".
+  # @param text [String]
+  # @return [String]
+  def self.slugify(text)
+    # NFC first: decomposed input (macOS filenames, some form posts) would otherwise
+    # split a Latin run on its combining marks — "São" => "sa-o".
+    latin = text.to_s.unicode_normalize(:nfc).delete('.').gsub(/\p{Latin}+/) do |word|
+      ActiveSupport::Inflector.transliterate(word.unicode_normalize(:nfkd).gsub(/\p{Mn}/, ''))
+    end
+    latin.gsub(/[^\p{Alnum}]+/, '-').gsub(/^-+|-+$/, '').downcase
+  end
+
   included do
-    # field :gid,    type: Integer # geonames id
+    # @!group Fields
 
+    # @!attribute [rw] name
+    #   @return [String] The primary name of the entity. Localized.
+    #   Automatically titleized on assignment if it doesn't contain mixed-case characters.
     field :name,    type: String, localize: true
-    field :abbr,    type: String
-    field :nick,    type: String
-
-    field :souls,   type: Fixnum  # Population
+    # @!attribute [rw] alt
+    #   @return [String, nil] An alternative name or spelling for the entity. Localized.
+    field :alt,     type: String, localize: true, default: nil
+    # @!attribute [rw] abbr
+    #   @return [String, nil] A common abbreviation for the entity (e.g., "NY" for New York).
+    field :abbr,    type: String, default: nil
+    # @!attribute [rw] nick
+    #   @return [String, nil] A nickname or colloquial name for the entity.
+    field :nick,    type: String, default: nil
 
-    field :ascii,   type: String
-    field :code,    type: String
-    field :slug,    type: String  # , default: -> { name }
-
-    field :postal,  type: String  # , default: -> { name }
-    field :phone,   type: String  # , default: -> { name }
+    # @!attribute [rw] souls
+    #   @return [Integer, nil] The population count of the entity. Note: `pop` was taken by mongoid
+    field :souls, type: Integer, default: nil
+    # @!attribute [rw] ascii
+    #   @return [String, nil] An ASCII-only representation of the name, useful for systems that don't support Unicode.
+    field :ascii,   type: String, default: nil
+    # @!attribute [rw] code
+    #   @return [String, nil] A code associated with the entity (e.g., FIPS code, ISO 3166-2 subdivision code).
+    #   Its uniqueness might be scoped by a parent entity (e.g., nation_id) in the including class.
+    field :code,    type: String, default: nil
+    # @!attribute [rw] slug
+    #   @return [String] A URL-friendly slug, automatically generated from the name if not provided.
+    #   Guaranteed to be present and unique across all documents including this concern.
+    field :slug,    type: String
+    # @!attribute [rw] postal
+    #   @return [String, nil] The primary postal code or prefix for the entity.
+    field :postal,  type: String, default: nil
+    # @!attribute [rw] phone
+    #   @return [String, nil] The primary phone dialing code for the entity.
+    field :phone,   type: String, default: nil
 
+    # @!group Aliases
+    # @!attribute [rw] population # This alias might still be problematic if Mongoid defines a 'population' method.
+    #   @see #souls  # For now, keeping it as it was a direct alias to 'pop'.
     alias_method :population, :souls
-    alias_method :iso_3166_2, :code
+    alias_method :population=, :souls=
 
+    # @!group Validations
     validates :name, presence: true
-    validates :slug, presence: true, uniqueness: true
-    validates :code, uniqueness: { allow_nil: true }
+    validates :slug, presence: true # Uniqueness will be handled by including models with appropriate scope
+    # @!endgroup
+
+    # @!group Indexes
+    # NOTE: no plain slug index here — each model declares its own (unique where it
+    # can be), and a duplicate key declaration would silently shadow theirs.
+    index({ name: 1 }) # For sorting and lookups by name
+    index({ abbr: 1 }, { sparse: true }) # Sparse as abbr can be nil
+    index({ code: 1 }, { sparse: true }) # Sparse as code can be nil
+    # @!endgroup
 
-    index slug: 1
-    index name: 1
+    before_validation :ensure_slug_is_generated
 
-    before_validation :ensure_slug
+    # @!group Scopes
+    # @!method self.ordered
+    #   @return [Mongoid::Criteria] Documents ordered by name ascending.
+    scope :ordered, -> { order_by(name: :asc) }
+    # @!endgroup
 
-    scope :ordered, -> { order_by(name: 1) }
+    # Ensures that a slug is generated from the name if the slug is currently blank.
+    # This method is called before validation.
+    # It uses the custom `slug=` setter which handles parameterization.
+    def ensure_slug_is_generated
+      return unless slug.blank? && name.present?
 
-    def ensure_slug
-      self.slug ||= name
+      self.slug = name # Will trigger the custom slug setter
     end
 
-    def name=(txt)
-      return unless txt
-      txt = txt.titleize unless txt =~ /[A-Z][a-z]/
-      super txt
+    # Custom writer for the name attribute.
+    # It titleizes the input string if it doesn't already contain mixed-case characters.
+    # @param new_name [String] The new name.
+    def name=(new_name)
+      if new_name.present? && new_name !~ /[A-Z][a-z]/
+        super(new_name.titleize)
+      else
+        super
+      end
     end
 
-    def slug=(txt)
-      return unless txt
-      self[:slug] = ActiveSupport::Inflector
-                    .transliterate(txt).delete('.').gsub(/\W/, '-').downcase
+    # Custom writer for the slug attribute. See {Geopolitocracy.slugify}.
+    # @param new_slug_source [String] The string to be converted into a slug.
+    def slug=(new_slug_source)
+      super(new_slug_source.present? ? Geopolitocracy.slugify(new_slug_source) : nil)
     end
 
+    # Default string representation of the entity.
+    # @return [String] The name of the entity, or its slug if the name is not set.
     def to_s
-      name || slug
+      name.presence || slug.presence || ''
     end
 
-    def self.search(txt, lazy = false)
-      key = ActiveSupport::Inflector.transliterate(txt).gsub(/\W/, '-')
-      char = lazy ? nil : '$'
-      where(slug: /^#{key}#{char}/i)
+    # @!group Class Methods
+    # Performs a search for entities where the slug starts with the given text (after parameterization).
+    #
+    # @param query_text [String] The text to search for.
+    # @param exact_match [Boolean] If true, searches for an exact match of the parameterized query.
+    #                             If false (default), searches for slugs starting with the parameterized query.
+    # @return [Mongoid::Criteria] A criteria object for fetching matching documents.
+    def self.search(query_text, exact: false)
+      return none if query_text.blank? # Return an empty criteria if query is blank
+
+      parameterized_query = Geopolitocracy.slugify(query_text)
+      return none if parameterized_query.blank?
+
+      if exact # matches the exact slug
+        where(slug: parameterized_query)
+      else
+        where(slug: /^#{Regexp.escape(parameterized_query)}/)
+      end
     end
+    # @!endgroup
   end
 end

data/app/models/hood.rb

@@ -1,35 +1,61 @@
+# frozen_string_literal: true
+
+# Represents a neighborhood (hood) within a city.
 #
-# Hood/Neighborhood
-#
+# Hoods belong to a city and inherit common geopolitical attributes
+# from the `Geopolitocracy` concern (like `name`, `abbr`, `slug`, `pop`, `phone`, `postal`).
+# The slug for a hood is typically a combination of the city's slug and the hood's name.
 class Hood
   include Mongoid::Document
-  include Geopolitocracy
+  include Geopolitocracy # Provides common geopolitical fields like name, abbr, slug, etc.
 
-  field :rank,  type: Integer
+  # @!attribute [rw] rank
+  #   @return [Integer, nil] An optional ranking for the neighborhood, if applicable.
+  field :rank, type: Integer
 
+  # @!attribute [rw] city
+  #   @return [City] The city this neighborhood belongs to. Required.
   belongs_to :city
 
   validates :city, presence: true
-  validates :name, uniqueness: { scope: :city_id }
+  validates :name, uniqueness: { scope: :city_id, message: 'must be unique within its city' }
+  # `abbr` (from Geopolitocracy) could also be validated for uniqueness within the city if used.
+  # validates :abbr,
+  #           uniqueness: { scope: :city_id, allow_nil: true, message: "must be unique within its city if provided" }
+
+  index({ city_id: 1, name: 1 }, { unique: true })
+  # index({ city_id: 1, abbr: 1 }, { unique: true, sparse: true }) # If abbr is used and needs to be unique
+  index({ slug: 1 }, { unique: true }) # Hood slugs are globally unique due to city_slug prefix
+
+  before_validation :ensure_slug_for_hood
 
-  def ensure_slug
-    return unless city
-    self.slug ||= "#{city.slug}-#{name}"
+  # Slug is "#{city.slug}-#{name slug}"; prepends the city slug if a bare one was
+  # given, and is rebuilt when the hood is renamed or moved to another city.
+  def ensure_slug_for_hood
+    return if city.blank?
+
+    self.slug = name if persisted? && (name_changed? || city_id_changed?)
+    return if slug.blank?
+
+    prefix = "#{city.slug}-"
+    self.slug = "#{prefix}#{slug}" unless slug.start_with?(prefix)
   end
 
+  # Retrieves the phone dialing code for the neighborhood.
+  # Falls back to the city's phone code if the neighborhood's is not set.
+  # Assumes `phone` field is provided by `Geopolitocracy`.
+  #
+  # @return [String, nil] The phone dialing code.
   def phone
-    self[:phone] || city.phone
+    self[:phone] || city&.phone
   end
 
+  # Retrieves the primary postal code for the neighborhood.
+  # Falls back to the city's postal code if the neighborhood's is not set.
+  # Assumes `postal` field is provided by `Geopolitocracy`.
+  #
+  # @return [String, nil] The postal code.
   def postal
-    self[:postal] || city.postal
-  end
-
-  def as_json(_opts = {})
-    {
-      id: id.to_s,
-      name: name,
-      city: city
-    }
+    self[:postal] || city&.postal
   end
 end

data/app/models/nation.rb

@@ -1,42 +1,121 @@
+# frozen_string_literal: true
+
+#
+# Represents a nation or country.
 #
-# Nation/Country/Flag
+# Each nation has a unique abbreviation (`abbr`) which also serves as its `_id`.
+# It includes geopolitical information such as its Geonames ID, top-level domain,
+# currency, ISO 3166-3 code, and languages.
 #
+# Nations can have a capital city, multiple regions, and multiple cities.
 class Nation
   include Mongoid::Document
   include Geopolitocracy
 
-  field :_id, type: String, default: -> { abbr }
+  # The unique identifier for the nation, defaults to its abbreviation.
+  # The `abbr` is expected to be provided by the Geopolitocracy concern or set explicitly.
+  field :_id, type: String, default: -> { abbr }, overwrite: true
 
-  field :gid,    type: Integer # geonames id
-  field :tld,    type: String # Top level domain
-  field :cash,   type: String # Currency prefix
-  field :code3,  type: String # Iso 3166_3
-  field :lang,   type: String # Official/main language
-  field :langs,  type: Array  # All official languages
+  # @!attribute [rw] gid
+  #   @return [Integer] The Geonames identifier for the nation.
+  field :gid,    type: Integer
+  # @!attribute [rw] tld
+  #   @return [String] The top-level domain (e.g., ".us", ".de").
+  field :tld,    type: String
+  # @!attribute [rw] cash
+  #   @return [String] The currency symbol or code (e.g., "$", "EUR").
+  field :cash,   type: String
+  # @!attribute [rw] code3
+  #   @return [String] The ISO 3166-1 alpha-3 code for the country.
+  field :code3,  type: String
+  # @!attribute [rw] langs
+  #   @return [Array<String>] A list of all official language codes.
+  field :langs,  type: Array, default: []
 
+  # Alias for the `cash` field.
+  # @return [String] The currency symbol or code.
   alias currency cash
-  alias iso_3166_3 code3
+  # Alias for the `cash=` writer.
+  alias currency= cash=
+
+  # Alias for the `code3` field, representing the ISO 3166-1 alpha-3 code.
+  # @return [String] The ISO 3166-1 alpha-3 code.
+  # alias iso_3166_3 code3
+  # # Alias for the `code3=` writer.
+  # alias iso_3166_3= code3=
 
-  validates :abbr, uniqueness: true, presence: true
+  validates :abbr, presence: true # Name presence is validated in Geopolitocracy
+  validates_uniqueness_of :abbr, case_sensitive: false
+  validates :slug, uniqueness: { message: 'must be unique' } # Slug presence is validated in Geopolitocracy
 
-  belongs_to :capital, inverse_of: :nation_capital, class_name: 'City',
-                       optional: true
+  # @!attribute [rw] capital
+  #   @return [City] The capital city of this nation.
+  belongs_to :capital, inverse_of: :nation_governancy, class_name: 'City', optional: true
 
+  # @!attribute [rw] regions
+  #   @return [Mongoid::Relations::Targets::Enumerable<Region>] The regions within this nation.
   has_many :regions, dependent: :destroy
+  # @!attribute [rw] cities
+  #   @return [Mongoid::Relations::Targets::Enumerable<City>] The cities within this nation.
   has_many :cities,  dependent: :destroy
 
-  index lang: 1
+  index({ name: 1 }) # Index for sorting by name, common operation
+  index({ slug: 1 }, { unique: true }) # Slugs must be globally unique for nations
+
+  # Nation['br'] => the Nation with abbr BR (the abbr is the _id), nil if unknown.
+  # @param abbr [String, Symbol]
+  # @return [Nation, nil]
+  def self.[](abbr) = where(_id: abbr.to_s.upcase).first
+
+  # A whimsical method indicating the planet.
+  # In a more complex system, this might point to a Planet model.
+  # @return [Symbol] Always returns `:earth`.
+  def planet
+    :earth # In a larger cosmological model, this could be `Planet.find_by(name: 'Earth')`
+  end
 
-  def abbr=(txt)
-    self[:abbr] = txt && txt.upcase
+  # Helper method to retrieve the primary language of the nation.
+  # This returns the first language in the `langs` array, if available.
+  #
+  # @return [String, nil] The primary language code or nil if no languages are set.
+  def lang
+    langs&.first
   end
 
+  # Sets the primary language, keeping any other languages the nation speaks.
+  # @param value [String, nil]
+  def lang=(value)
+    rest = langs.to_a.drop(1)
+    self.langs = value.present? ? [value.to_s, *rest] : rest
+  end
+
+  # Sets the abbreviation for the nation.
+  # The abbreviation is automatically converted to uppercase.
+  #
+  # @param new_abbr [String] The new abbreviation.
+  # @return [String, nil] The uppercased abbreviation or nil if input was nil.
+  def abbr=(new_abbr)
+    super(new_abbr&.upcase)
+  end
+
+  # Compares this nation with another object for equality.
+  # Nations are considered equal if their abbreviations are the same.
+  #
+  # @param other [Object] The object to compare with.
+  # @return [Boolean] True if the other object is a Nation and has the same abbreviation, false otherwise.
   def ==(other)
-    return unless other
-    abbr == other.abbr
+    other.is_a?(Nation) && abbr == other.abbr
   end
 
+  # Compares this nation with another nation for sorting purposes.
+  # Comparison is based on the nation's name.
+  #
+  # @param other [Nation] The other nation to compare with.
+  # @return [-1, 0, 1] -1 if self.name < other.name, 0 if equal, 1 if self.name > other.name.
+  # @raise [ArgumentError] if other is not a Nation.
   def <=>(other)
+    return nil unless other.is_a?(Nation) # Or raise ArgumentError?
+
     name <=> other.name
   end
 end