API doc updates

lib/dotenv/cli.rb

@@ -4,7 +4,7 @@
 require "optparse"
 
 module Dotenv
-  # The command line interface
+  # The `dotenv` command line interface. Run `$ dotenv --help` to see usage.
   class CLI < OptionParser
     attr_reader :argv, :filenames, :overwrite
 

lib/dotenv/environment.rb

@@ -1,9 +1,12 @@
 module Dotenv
-  # This class inherits from Hash and represents the environment into which
-  # Dotenv will load key value pairs from a file.
+  # A `.env` file that will be read and parsed into a Hash
   class Environment < Hash
     attr_reader :filename, :overwrite
 
+    # Create a new Environment
+    #
+    # @param filename [String] the path to the file to read
+    # @param overwrite [Boolean] whether the parser should assume existing values will be overwritten
     def initialize(filename, overwrite: false)
       super()
       @filename = filename

lib/dotenv/log_subscriber.rb

@@ -1,6 +1,13 @@
 require "active_support/log_subscriber"
 
 module Dotenv
+  # Logs instrumented events
+  #
+  # Usage:
+  #   require "active_support/notifications"
+  #   require "dotenv/log_subscriber"
+  #   Dotenv.instrumenter = ActiveSupport::Notifications
+  #
   class LogSubscriber < ActiveSupport::LogSubscriber
     attach_to :dotenv
 

lib/dotenv/parser.rb

@@ -2,11 +2,11 @@
 require "dotenv/substitutions/command" if RUBY_VERSION > "1.8.7"
 
 module Dotenv
+  # Error raised when encountering a syntax error while parsing a .env file.
   class FormatError < SyntaxError; end
 
-  # This class enables parsing of a string for key value pairs to be returned
-  # and stored in the Environment. It allows for variable substitutions and
-  # exporting of variables.
+  # Parses the `.env` file format into key/value pairs.
+  # It allows for variable substitutions, command substitutions, and exporting of variables.
   class Parser
     @substitutions =
       [Dotenv::Substitutions::Variable, Dotenv::Substitutions::Command]