rv is the new kid in town

Recently, I've been helping the fine folk at Spinel work on rv, the well-known Ruby version manager written in Rust. I've made some small fixes^[1] but I am working on something a bit larger: introducing something akin to documentation testing found in Rust to Ruby. You can check the stacked PRs starting here. This is the first time I've used the Stacked Pull Request feature on GitHub; it feels like operational sugar over something I've done manually - it's cool!

Working on rv has been fun. Ruby's also the language that got me cemented in my professional software journey. I do have a question for you (if you write Ruby often): how do you structure your code comments? I'm talking about things akin to:

# The collection of foods you shouldn't eat because of their
# non-nutritional properties.
#
# ```ruby
# bean = MagicFoods.BeanTower.new()
# bean.sprout()
# ```
module MagicFoods

  # A bean to architectural artifact. Do not use in chili.
  #
  # ```ruby
  # tower = BeanTower.new()
  # ```
  class BeanTower
    def new(height: 30_000)
      self.height = height
    end

    def sprout
      puts "I _am_ a magic bean sprout at #{self.height}!"
    end
  end

  class PumpkinVehicle

    # A vehicle to drive around in.
    #
    # ```ruby
    # vehicle = PumpkinVehicle.new()
    #
    # ```
    def drive(distance: 30_000)
      puts "Let's go #{distance}!"
    end
  end
end

I'm hoping to have the PR adapt to as many styles as possible but if we stick to a convention, it'll be possible to run code blocks of Ruby code and have it operate as living documentation. Things like YARD make this a bit easier because of the stricter organization of comment information and with the advent of RBS, we might even get a means of having types and documentation living in sidecar files if not immediately in the code itself (I'd prefer the documentation to live with the code, to be frank).