Add doc comments to classes and modules in /lib. NEXT: Markdown docs.

app/lib/celery_script/argument_specification.rb

@@ -1,3 +1,4 @@
+# Define how a particular argument should behave in a corpus.
 module CeleryScript
   NOOP = ->(*_) { }
   class ArgumentSpecification

app/lib/celery_script/ast_base.rb

@@ -1,3 +1,4 @@
+# Base calss for every "thing" that is found in a CeleryScript AST.
 module CeleryScript
   # Abstract class that AstLeaf and AstNode inherit from.
   # Use this for shared leaf/node behavior.

app/lib/celery_script/ast_leaf.rb

@@ -1,3 +1,6 @@
+# When climbing the abstract syntax tree, any unparsable data is converted into
+# a "leaf" type. It is a wrapper object around the original data, accessible via
+# `.value`.
 module CeleryScript
   class AstLeaf < AstBase
     attr_reader :kind, :value, :parent

app/lib/celery_script/ast_node.rb

@@ -1,3 +1,6 @@
+# An AST Node in celery script MUST have a `kind` property (string) and an
+# `args` property (dictionary). It also may have a `body`, which is an array of
+# other nodes (optional).
 module CeleryScript
   class AstNode < AstBase
       attr_reader :args, :body, :comment, :kind, :parent

app/lib/celery_script/checker.rb

@@ -1,3 +1,5 @@
+# Takes a corpus and an AST and tells you if it is syntactically valid.
+# PROBABLY THE MOST COMPLICATED CODE IN ALL OF FARMBOT.
 module CeleryScript
   class TypeCheckError < StandardError; end
   class Checker

app/lib/celery_script/corpus.rb

@@ -1,3 +1,5 @@
+# A Corpus is a dictionary describing every kind of node and argument that is
+# allowed in the abstract syntax tree.
 module CeleryScript
   class Corpus
     BAD_NODE_NAME = "Can't find validation rules for node "

app/lib/celery_script/node_specification.rb

@@ -1,3 +1,5 @@
+# Describes the allowed arguments and body types of CeleryScript node.
+# Eg: Which arguments does it take? Whic nodes can be placed in the body field?
 module CeleryScript
   class NodeSpecification
     attr_reader :name, :allowed_args, :allowed_body_types

app/lib/celery_script/tree_climber.rb

@@ -1,3 +1,5 @@
+# PROBLEM THIS CLASS SOLVES: You need to run a function against every node in
+#    an abstract syntax tree, usually for validation or type checking.
 module CeleryScript
   class TreeClimber
     def self.travel(node, callable)
@@ -7,14 +9,14 @@ module CeleryScript
 
     def self.find_all_by_kind(node, name)
       results = []
-      filter = -> (node) { results.push(node) if node.kind == name }
+      filter = -> (n) { results.push(n) if n.kind == name }
       travel(node, filter)
       results
     end
 
     def self.find_all_with_arg(node, arg_name)
       results = []
-      filter = -> (node) { results.push(node) if node.args.has_key?(arg_name) }
+      filter = -> (n) { results.push(n) if n.args.has_key?(arg_name) }
       travel(node, filter)
       results
     end

app/lib/haikunator.rb

@@ -1,3 +1,6 @@
+# This is a module that generates cool names like "billowing-raindrop-48".
+# We originally used the usmanbashir/haikunator gem, but forked the code to begin
+# more "plant friendly".
 module Haikunator
   class << self
     def haikunate(token_range = 9999, delimiter = "-")

app/lib/key_gen.rb

@@ -1,8 +1,10 @@
-# Service for creating key pairs for cryptographically secure operations.
+# Creates asymetric key pairs for cryptographically secure operations.
 # Mostly used for creation of jwt.pem- which is used to verify authenticity of
 # JSON Web Tokens
 class KeyGen
-  SAVE_PATH = (Rails.env == "production") ? "/keys/production.pem" : "jwt.#{Rails.env}.pem"
+  PROD_KEY_FILE    = "/keys/production.pem"
+  KEY_FILE         = "jwt.#{Rails.env}.pem"
+  SAVE_PATH        = (Rails.env == "production") ? PROD_KEY_FILE : KEY_FILE
 
   def self.try_file
     OpenSSL::PKey::RSA.new(File.read(SAVE_PATH)) if File.file?(SAVE_PATH)

app/lib/mutations/time_filter.rb

@@ -1,3 +1,5 @@
+# This filter was created by a mutations contributor but was not accepted into
+# master. I have copy/pasted it here for our own use.
 module Mutations
   class TimeFilter < AdditionalFilter
     @default_options = {

app/lib/password_reset_token.rb

@@ -1,3 +1,4 @@
+# A JSON Web Token (JWT) used only for password resets.
 class PasswordResetToken < AbstractJwtToken
   EXPIRY = 24.hours
   AUD    = "PASSWORD_RESETER"

app/lib/sequence_migration.rb

@@ -1,13 +1,28 @@
+# PROBLEM: As time passes, we must update the format and structure of sequences
+#          created by users. Backwards incompatibilities and breaking changes
+#          over time will cause sequences to become outdated. Forcing users to
+#          update their sequences manually after updates is tedious and error
+#           prone.
+# SOLUTION: Every time we make a breaking change to the way Sequences work, we
+#           write a migration to go along with it. Migrations run one-at-a-time
+#           and ensure that sequences never become incompatible with new
+#           features.
+# HOW:      To create a new migration, create a subclass of SequenceMigration.
+#           Give it a VERSION number and a CREATED_ON date. Add the class name
+#           to the array in SequenceMigration::Base.descendants. Perform all
+#           transformations inside of the #up() method. The migration will
+#           automagically run if the API determines a sequence is out of date.
 module SequenceMigration
   class Base
-    # Assume that versionless sequences are "legacy" sequences from a time before
-    # versioning. Since the lowest migration version is 0, a version of -1 will
-    # require all migrations
+    # MAGIC NUMBER. Assume that versionless sequences are "legacy" sequences
+    # from a time before versioning. Since the lowest migration version is 0, a
+    # version of -1 will require all migrations to run.
     LEGACY_VERSION = -1
     VERSION        = "YOU MUST CHANGE THIS!!!"
 
     # I shouldn't need to do this, as this method comes with ActiveSupport, but
-    # its acting weird with autoloading right now :shipit:.
+    # its acting weird with autoloading right now :shipit:. TODO: See if there
+    # is a way to automatically infer all classes
     def self.descendants
       [
         AddVersionInfo,

app/lib/session_token.rb

@@ -1,3 +1,5 @@
+# Generates a JSON Web Token (JWT) for a given user. Typically placed in the
+# `Authorization` header, or used a password to gain access to the MQTT server.
 class SessionToken < AbstractJwtToken
   MUST_VERIFY = 'Verify account first'
   DEFAULT_OS = "https://api.github.com/repos/" \