add YARD docs for all files in lib/ and app/

app/controllers/passwordless/application_controller.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
+# Namespace for classes and modules that handle the MVC for the
+# passwordless Gem.
+# This is the main module for this gem.
 module Passwordless
+ # Base Controller Class. All controllers inherit from here.
  class ApplicationController < ::ApplicationController
+ # Always returns true. Used to check if <Some>Controller inherits
+ # from ApplicationController.
+ # @return [boolean]
  def passwordless_controller?
  true
  end

app/controllers/passwordless/sessions_controller.rb

@@ -3,16 +3,24 @@
 require 'bcrypt'
 
 module Passwordless
+ # Controller to manage RESTful methods for Sessions.
  class SessionsController < ApplicationController
  include ControllerHelpers
 
  helper_method :authenticatable_resource
 
+ # Controller#Method for Route: get '/sign_in'.
+ # Assigns an email_field and new Session to be used by new view.
+ # renders sessions/new.html.erb.
  def new
  @email_field = email_field
  @session = Session.new
  end
 
+ # Controller#Method for Route: post '/sign_in'.
+ # Saves a new Session. Sends out a Mailer
+ # renders sessions/create.html.erb.
+ # @see Mailer#magic_link Mailer#magic_link
  def create
  authenticatable = find_authenticatable
 
@@ -29,6 +37,11 @@ def create
  render
  end
 
+ # Controller#Method for Route: get '/sign_in/:token'.
+ # Uses a token to sign user in.
+ # will try to redirect to either some reset path or the root_path.
+ # @see ControllerHelpers#sign_in
+ # @see ControllerHelpers#reset_passwordless_redirect_location!
  def show
  # Make it "slow" on purpose to make brute-force attacks more of a hassle
  BCrypt::Password.create(params[:token])
@@ -46,6 +59,10 @@ def show
  end
  end
 
+ # Controller#Method for Route: match '/sign_out', via: %i[get delete].
+ # Signs user out.
+ # redirects to root_path
+ # @see ControllerHelpers#sign_out
  def destroy
  sign_out authenticatable_class
  redirect_to main_app.root_path

app/mailers/passwordless/mailer.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 module Passwordless
- # The mailer responsible for sending Passwordless' mails
+ # The mailer responsible for sending Passwordless' mails.
  class Mailer < ActionMailer::Base
  default from: Passwordless.default_from_address
 
+ # Sends a magic link (secret token) email to allow sign in with
+ # link straight from email.
+ # @param session [Object] the rails session Object.
  def magic_link(session)
  @session = session
 

app/models/passwordless/application_record.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Passwordless
+ # Classic Rails class to abstractify and insulate ActiveRecord:Base.
  class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true
  end

app/models/passwordless/session.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Passwordless
- # The session responsible holding the connection between the record trying to
- # log in and the unique tokens.
+ # The session responsible for holding the connection between the record
+ # trying to log in and the unique tokens.
  class Session < ApplicationRecord
  belongs_to :authenticatable,
  polymorphic: true, inverse_of: :passwordless_sessions

lib/passwordless/controller_helpers.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module Passwordless
+ # Some helpers for controllers that are connected to passswordless Models.
+ # These helpers give the ability to sign_in/out of a session, authenticate a
+ # session, and save/reset the passwordless redirect path.
  module ControllerHelpers
+ # Authenticate a model using cookies. Will create a key from the model name
+ # and check if there is a value in cookies for that key.
+ # @param authenticatable_class [Object] any Model connected to passwordless.
+ # ( e.g - User or Admin ).
+ # @return [Object, nil] an instance of Model found by id stored in
+ # cookies.encrypted at key: key_from_model_name,
+ # or nil if no value corresponds to that key.
  def authenticate_by_cookie(authenticatable_class)
  key = cookie_name(authenticatable_class)
  authenticatable_id = cookies.encrypted[key]
@@ -10,22 +20,39 @@ def authenticate_by_cookie(authenticatable_class)
  authenticatable_class.find_by(id: authenticatable_id)
  end
 
+ # Signs in user by assigning her id to a permanent cookie.
+ # @param authenticatable [Object] instance of Model to sign in
+ # ( e.g - @user when @user = User.find(id: some_id) ).
+ # @return [Object] the Object that is passed in.
  def sign_in(authenticatable)
  key = cookie_name(authenticatable.class)
  cookies.encrypted.permanent[key] = { value: authenticatable.id }
  authenticatable
  end
 
+ # Signs out user by deleting her id from permanent cookies.
+ # @param (see #authenticate_by_cookie)
+ # @return [Integer, nil] the id that was deleted from cookies, or nil
+ # if no value found for provided key.
  def sign_out(authenticatable_class)
  key = cookie_name(authenticatable_class)
  cookies.encrypted.permanent[key] = { value: nil }
  cookies.delete(key)
  end
 
+ # Saves request.original_url as the redirect location
+ # for a passwordless Model.
+ # @param (see #authenticate_by_cookie)
+ # @return [String] the redirect url that was just saved.
  def save_passwordless_redirect_location!(authenticatable_class)
  session[session_key(authenticatable_class)] = request.original_url
  end
 
+ # Resets the redirect_location to root_path by deleting the
+ # redirect_url fromsession.
+ # @param (see #authenticate_by_cookie)
+ # @return [String, nil] the redirect url that was just deleted,
+ # or nil if no url found for given Model.
  def reset_passwordless_redirect_location!(authenticatable_class)
  session.delete session_key(authenticatable_class)
  end

lib/passwordless/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Passwordless
+ # Engine that runs the passwordless gem.
  class Engine < ::Rails::Engine
  isolate_namespace Passwordless
 

lib/passwordless/model_helpers.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 module Passwordless
- # Some helpers for models that can sign in passswordlessly
+ # Some helpers for models that can sign in passswordlessly. These helpers
+ # are used to hook up SomeModel with passwordless_sessions.
  module ModelHelpers
+ # Adds passwordless sign_in for SomeModel (examples: User, Admin).
+ # Creates relationship - has_many :passwordless_sessions
+ # Allows - Call SomeModel.passwordless_email_field to return email used.
+ # @param field [string] email submitted by user.
  def passwordless_with(field)
  has_many :passwordless_sessions, class_name: 'Passwordless::Session'
  define_singleton_method(:passwordless_email_field) { field }

lib/passwordless/router_helpers.rb

@@ -1,7 +1,18 @@
 # frozen_string_literal: true
 
 module Passwordless
+ # Some helpers for generating passwordless routes.
  module RouterHelpers
+ # Generates passwordless routes for any Model connected to Passwordless.
+ # Example usage:
+ # passwordless_for :users, at: 'session_stuff', as: :user_session_things
+ # @param resource [Symbol] the pluralized symbol of a Model (e.g - :users).
+ # @param at [String] Optional - provide custom path for the passwordless
+ # engine to get mounted at (using the above example your URLs end
+ # up like: /session_stuff/sign_in)
+ # @param as [Symbol] Optional - provide custom scope for url
+ # helpers (using the above example in a view:
+ # <%= link_to 'Sign in', user_session_things.sign_in_path %>)
  def passwordless_for(resource, at: nil, as: nil)
  mount(
  Passwordless::Engine,

lib/passwordless/url_safe_base_64_generator.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Passwordless
+ # Generates secure random numbers for sessions/cookies, etc.
  class UrlSafeBase64Generator
+ # Generates a url safe base64 secure random number :-)
+ # @param _session [Object] Optional - pass the session into the generator
+ # to allow using it with a custom token generator.
+ # @return [string] secure 32 byte base64 string.
  def call(_session)
  SecureRandom.urlsafe_base64(32)
  end

lib/passwordless/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Passwordless
+ # The current version of Passwordless.
  VERSION = '0.4.1'
 end