Add basic YARD docs

.rubocop_todo.yml

@@ -19,13 +19,3 @@ Style/Documentation:
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
-    - 'lib/consent.rb'
-    - 'lib/consent/rspec.rb'
-    - 'lib/consent/ability.rb'
-    - 'lib/consent/action.rb'
-    - 'lib/consent/dsl.rb'
-    - 'lib/consent/permission.rb'
-    - 'lib/consent/permissions.rb'
-    - 'lib/consent/subject.rb'
-    - 'lib/consent/view.rb'
-    - 'lib/generators/consent/permissions_generator.rb'

lib/consent.rb

@@ -10,23 +10,42 @@
 require 'consent/ability' if defined?(CanCan)
 require 'consent/railtie' if defined?(Rails)
 
+# Consent makes defining permissions easier by providing a clean,
+# concise DSL for authorization so that all abilities do not have
+# to be in your `Ability` class.
 module Consent
   FULL_ACCESS = %w[1 true].freeze
 
+  # Default views available to every permission
+  #
+  # i.e.:
+  #  Defining a view with no conditions:
+  #  Consent.default_views[:all] = Consent::View.new(:all, "All")
+  #
+  # @return [Hash<Symbol,Consent::View>]
   def self.default_views
     @default_views ||= {}
   end
 
+  # Subjects defined in Consent
+  #
+  # @return [Array<Consent::Subject>]
   def self.subjects
     @subjects ||= []
   end
 
+  # Finds all subjects defined with the given key
+  #
+  # @return [Array<Consent::Subject>]
   def self.find_subjects(subject_key)
     @subjects.find_all do |subject|
       subject.key.eql?(subject_key)
     end
   end
 
+  # Finds an action within a subject context
+  #
+  # @return [Consent::Action,nil]
   def self.find_action(subject_key, action_key)
     Consent.find_subjects(subject_key)
            .map(&:actions).flatten
@@ -35,25 +54,46 @@ def self.find_action(subject_key, action_key)
            end
   end
 
+  # Finds a view within a subject context
+  #
+  # @return [Consent::View,nil]
   def self.find_view(subject_key, view_key)
     views = Consent.find_subjects(subject_key)
                    .map(&:views)
                    .reduce({}, &:merge)
     views[view_key]
   end
 
+  # Loads all permission (ruby) files from the given directory
+  # and using the given mechanism (default: :require)
+  #
+  # @param paths [Array<String,#to_s>] paths where the ruby files are located
+  # @param mechanism [:require,:load] mechanism to load the files
   def self.load_subjects!(paths, mechanism = :require)
     permission_files = paths.map { |dir| File.join(dir, '*.rb') }
     Dir[*permission_files].each(&Kernel.method(mechanism))
   end
 
+  # Defines a subject with the given key, label and options
+  #
+  # i.e:
+  #   Consent.define :users, "User management" do
+  #     view :department, "Same department only" do |user|
+  #       { department_id: user.department_id }
+  #     end
+  #     action :read, "Can view users"
+  #     action :update, "Can edit existing user", views: :department
+  #   end
   def self.define(key, label, options = {}, &block)
     defaults = options.fetch(:defaults, {})
     subjects << Subject.new(key, label).tap do |subject|
       DSL.build(subject, defaults, &block)
     end
   end
 
+  # Maps a permissions hash to a Consent::Permissions
+  #
+  # @return [Consent::Permissions]
   def self.permissions(permissions)
     Permissions.new(permissions)
   end

lib/consent/ability.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
+  # Defines a CanCan(Can)::Ability class based on a permissions hash
   class Ability
     include CanCan::Ability
 

lib/consent/action.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
-  class Action
+  class Action # :nodoc:
     attr_reader :key, :label, :options
 
     def initialize(key, label, options = {})

lib/consent/dsl.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
-  class DSL
+  class DSL # :nodoc:
     attr_reader :subject
 
     def initialize(subject, defaults)

lib/consent/permission.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
-  class Permission
+  class Permission # :nodoc:
     def initialize(subject, action, view = nil)
       @subject = subject
       @action = action

lib/consent/permissions.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
-  class Permissions
+  class Permissions # :nodoc:
     include Enumerable
 
     def initialize(permissions)

lib/consent/rspec.rb

@@ -3,6 +3,31 @@
 require 'consent'
 
 module Consent
+  # RSpec helpers for consent. Given permissions are loaded,
+  # gives you the ability of defining permission specs like
+  #
+  # Given "users" permissions
+  # Consent.define :users, "User management" do
+  #   view :department, "Same department only" do |user|
+  #     { department_id: user.department_id }
+  #   end
+  #   action :read, "Can view users"
+  #   action :update, "Can edit existing user", views: :department
+  # end
+  #
+  # RSpec.describe "User permissions" do
+  #   include Consent::Rspec
+  #   let(:user) { double(department_id: 15) }
+  #
+  #   it do
+  #     is_expected.to consent_view(:department, department_id: 15).to(user)
+  #   end
+  #   it { is_expected.to consent_action(:read) }
+  #   it { is_expected.to consent_action(:update).with_views(:department) }
+  # end
+  #
+  # Find more examples at:
+  # https://github.com/powerhome/consent
   module Rspec
     extend RSpec::Matchers::DSL
 

lib/consent/subject.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
-  class Subject
+  class Subject # :nodoc:
     attr_reader :key, :label, :actions, :views
 
     def initialize(key, label)

lib/consent/view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
-  class View
+  class View # :nodoc:
     attr_reader :key, :label
 
     def initialize(key, label, instance = nil, collection = nil)

lib/generators/consent/permissions_generator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Consent
-  class PermissionsGenerator < Rails::Generators::NamedBase
+  class PermissionsGenerator < Rails::Generators::NamedBase # :nodoc:
     source_root File.expand_path('templates', __dir__)
     argument :description, type: :string, required: false