documented all models until StatisticField + fixes halting callback chains via returning false + improved some code

app/models/address.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Address is a database record that can be placed on a map.
 class Address < ApplicationRecord
   belongs_to :placeable, polymorphic: true
 end

app/models/age_range.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# AgeRange is an optional filter used to categorize Events
 class AgeRange < ApplicationRecord
   extend FriendlyId
   friendly_id :name, use: :slugged

app/models/auth_provider.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# AuthProvider is a configuration record, storing parameters of an external Single-Sign On server
 class AuthProvider < ApplicationRecord
   # this is a simple stub used for database creation & configuration
   class SimpleAuthProvider < Object

app/models/availability_tag.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# Abuse is a relation table between Availability and Tag.
+# Associating a Tag to an Availability restrict it for reservation to users with the same Tag.
 class AvailabilityTag < ApplicationRecord
   belongs_to :availability
   belongs_to :tag

app/models/category.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# Category is a first-level filter, used to categorize Events.
+# It is mandatory to choose a Category when creating an event.
 class Category < ApplicationRecord
   extend FriendlyId
   friendly_id :name, use: :slugged

app/models/component.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Component is a material that can be used in Projects.
 class Component < ApplicationRecord
   has_and_belongs_to_many :projects, join_table: 'projects_components'
   validates :name, presence: true, length: { maximum: 50 }

app/models/credit.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Credit is a way to offer free reservations for subscribing members.
 class Credit < ApplicationRecord
   belongs_to :creditable, polymorphic: true
   belongs_to :plan

app/models/custom_asset_file.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# CustomAssetFile is a file stored on the file system, associated with a CustomAsset.
 class CustomAssetFile < Asset
   mount_uploader :attachment, CustomAssetsUploader
 end

app/models/database_provider.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# DatabaseProvider is a special type of AuthProvider which provides the default app authentication method.
+# This method uses Devise and the local database.
 class DatabaseProvider < ApplicationRecord
   has_one :auth_provider, as: :providable, dependent: :destroy
 

app/models/event.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Event is an happening organized by the Fablab about a general topic, which does not involve Machines or trainings member's skills.
 class Event < ApplicationRecord
   include NotifyWith::NotificationAttachedObject
   include ApplicationHelper

app/models/event_file.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Event PDF attachements
+# EventFile is a PDF attachment for Events
 class EventFile < Asset
   mount_uploader :attachment, EventFileUploader
 

app/models/event_image.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# EventImage is the main picture for an Events.
 class EventImage < Asset
   include ImageValidatorConcern
   mount_uploader :attachment, EventImageUploader

app/models/event_price_category.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# EventPriceCategory is the relation table between Event and PriceCategory.
 class EventPriceCategory < ApplicationRecord
   belongs_to :event
   belongs_to :price_category
@@ -10,8 +13,9 @@ class EventPriceCategory < ApplicationRecord
   before_destroy :verify_no_associated_tickets
 
   protected
+
   def verify_no_associated_tickets
-    tickets.count == 0
+    throw(:abort) if tickets.count.zero?
   end
 
 end

app/models/event_theme.rb

@@ -1,11 +1,14 @@
+# frozen_string_literal: true
+
+# EventTheme is an optional filter used to categorize Events
 class EventTheme < ApplicationRecord
   extend FriendlyId
   friendly_id :name, use: :slugged
 
-  has_and_belongs_to_many :events, join_table: :events_event_themes, dependent: :destroy
+  has_and_belongs_to_many :events, join_table: 'events_event_themes', dependent: :destroy
 
   def safe_destroy
-    if self.events.count == 0
+    if events.count.zero?
       destroy
     else
       false

app/models/invoice_item.rb

@@ -7,7 +7,7 @@ class InvoiceItem < ApplicationRecord
   belongs_to :invoice
   belongs_to :subscription
 
-  has_one :invoice_item # to associated invoice_items of an invoice to invoice_items of an avoir
+  has_one :invoice_item # associates invoice_items of an invoice to invoice_items of an Avoir
 
   after_create :chain_record
   after_update :log_changes

app/models/licence.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Licence is an agreement about intellectual property that can be used in Projects.
 class Licence < ApplicationRecord
 
   has_many :projects

app/models/machine.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Machine is an hardware equipment hosted in the fablab that is available for reservation to the members
+# Machine is an hardware equipment hosted in the Fablab that is available for reservation to the members
 class Machine < ApplicationRecord
   extend FriendlyId
   friendly_id :name, use: :slugged

app/models/machine_file.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# MachineFile is a file stored on the file system, associated with a Machine.
+# It is known as an attachment for a space, in the user interface.
 class MachineFile < Asset
   mount_uploader :attachment, MachineFileUploader
 end

app/models/machine_image.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# MachineImage is the main picture for a Machine
 class MachineImage < Asset
   mount_uploader :attachment, MachineImageUploader
 end

app/models/machines_availability.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# MachinesAvailability is the relation table between a Machine and an Availability.
+# It defines periods in the agenda, when the given machine can be reserved by members.
 class MachinesAvailability < ApplicationRecord
   belongs_to :machine
   belongs_to :availability
@@ -7,10 +11,10 @@ class MachinesAvailability < ApplicationRecord
   # availability if the deleted machine was the last of this availability slot, and the availability is not
   # currently being destroyed.
   def cleanup_availability
-    unless availability.destroying
-      if availability.machines_availabilities.size == 0
-        availability.safe_destroy
-      end
-    end
+    return if availability.destroying
+
+    return unless availability.machines_availabilities.empty?
+
+    availability.safe_destroy
   end
 end

app/models/notification.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Notification is an in-system alert that is shown to a specific user until it is marked as read.
 class Notification < ApplicationRecord
   include NotifyWith::Notification
 

app/models/notification_type.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# NotificationType defines the different types of Notification.
 class NotificationType
   include NotifyWith::NotificationType
 

app/models/o_auth2_mapping.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# OAuth2Mapping defines a database field, saving user's data, that is mapped to an external API, that is authorized
+# through an external SSO of type oAuth 2
 class OAuth2Mapping < ApplicationRecord
   belongs_to :o_auth2_provider
 end

app/models/o_auth2_provider.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# OAuth2Provider is a special type of AuthProvider which provides authentication through an external SSO server using
+# the oAuth 2.0 protocol.
 class OAuth2Provider < ApplicationRecord
   has_one :auth_provider, as: :providable
   has_many :o_auth2_mappings, dependent: :destroy

app/models/offer_day.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# OfferDay provides a way for admins to extend the subscription of a member for free.
 class OfferDay < ApplicationRecord
   include NotifyWith::NotificationAttachedObject
 

app/models/open_api.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# OpenAPI provides an way for external apps to use Fab-manager's data through a REST API.
 module OpenAPI
   def self.table_name_prefix
     'open_api_'

app/models/organization.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# Organization is a special attribute for a member, used to mark him as corporation or a non-profit organization.
+# This is mainly used for invoicing.
 class Organization < ApplicationRecord
   belongs_to :profile
   belongs_to :invoicing_profile

app/models/plan_file.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# PlanFile is a file stored on the file system, associated with a Plan.
+# It is known as an information sheet for a plan, in the user interface.
 class PlanFile < Asset
   mount_uploader :attachment, PlanFileUploader
 end

app/models/plans_availability.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# PlansAvailability is the relation table between a Plan and an Availability.
+# An Availability which is associated with a Plan can only be booked by members having subscribed to this Plan.
 class PlansAvailability < ApplicationRecord
   belongs_to :plan
   belongs_to :availability

app/models/price.rb

@@ -29,16 +29,16 @@ class Price < ApplicationRecord
       all_elements[:slots] = []
 
       # initialize Plan
-      if user.subscribed_plan
-        plan = user.subscribed_plan
-        new_plan_being_bought = false
-      elsif plan_id
-        plan = Plan.find(plan_id)
-        new_plan_being_bought = true
-      else
-        plan = nil
-        new_plan_being_bought = false
-      end
+      plan = if user.subscribed_plan
+               new_plan_being_bought = false
+               user.subscribed_plan
+             elsif plan_id
+               new_plan_being_bought = true
+               Plan.find(plan_id)
+             else
+               new_plan_being_bought = false
+               nil
+             end
 
       # === compute reservation price ===
 

app/models/price_category.rb

@@ -1,13 +1,19 @@
+# frozen_string_literal: true
+
+# PriceCategory is a way to segment prices for an Event.
+# By default, each Events have a standard price but you may want, for example, to define a reduced fare for students,
+# and another reduced fare for children under 8. Each of these prices are defined in an EventPriceCategory.
+# You can choose to use each PriceCategory or not, for each Event you create.
 class PriceCategory < ApplicationRecord
   has_many :event_price_category
   has_many :events, through: :event_price_categories
 
-  validates :name, :presence => true
-  validates :name, uniqueness: {case_sensitive: false}
-  validates :conditions, :presence => true
+  validates :name, presence: true
+  validates :name, uniqueness: { case_sensitive: false }
+  validates :conditions, presence: true
 
   def safe_destroy
-    if event_price_category.count == 0
+    if event_price_category.count.zero?
       destroy
     else
       false

app/models/project_cao.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# CAO file attached to a project documentation
+# CAD file attached to a project documentation
 class ProjectCao < Asset
   mount_uploader :attachment, ProjectCaoUploader
 

app/models/project_step.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# ProjectStep is a detail in the documentation of a Project.
 class ProjectStep < ApplicationRecord
   belongs_to :project
   has_many :project_step_images, as: :viewable, dependent: :destroy

app/models/project_step_image.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Images for the documentation of a project step
+# Images for the documentation of a ProjectStep
 class ProjectStepImage < Asset
   include ImageValidatorConcern
   mount_uploader :attachment, ProjectImageUploader

app/models/project_user.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# ProjectUser is the relation table between a Project and an User.
+# Users are collaborators to a Project, with write access if they have confirmed their participation.
 class ProjectUser < ApplicationRecord
   include NotifyWith::NotificationAttachedObject
 
@@ -9,10 +13,12 @@ class ProjectUser < ApplicationRecord
   after_update :notify_project_author_when_collaborator_valid, if: :saved_change_to_is_valid?
 
   private
+
   def generate_valid_token
-    begin
+    loop do
       self.valid_token = SecureRandom.hex
-    end while self.class.exists?(valid_token: valid_token)
+      break unless self.class.exists?(valid_token: valid_token)
+    end
   end
 
   def notify_project_collaborator_to_valid

app/models/reservation.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Reservation is a Slot or a Ticket booked by a member.
+# Slots are for Machine, Space and Training reservations.
+# Tickets are for Event reservations.
 class Reservation < ApplicationRecord
   include NotifyWith::NotificationAttachedObject
 

app/models/role.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# Role is a authorization level for users in the application.
+# Currently, possible roles are: admin or member
 class Role < ApplicationRecord
   has_and_belongs_to_many :users, join_table: 'users_roles'
   belongs_to :resource, polymorphic: true

app/models/slot.rb

@@ -2,7 +2,7 @@
 
 # Time range of duration defined by ApplicationHelper::SLOT_DURATION, slicing an Availability.
 # During a slot a Reservation is possible
-# Only reserved slots are persisted in DB, others are instanciated on the fly
+# Only reserved slots are persisted in DB, others are instantiated on the fly
 class Slot < ApplicationRecord
   include NotifyWith::NotificationAttachedObject
 

app/models/slots_reservation.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# SlotsReservation is the relation table between a Slot and a Reservation.
 class SlotsReservation < ApplicationRecord
   belongs_to :slot
   belongs_to :reservation
@@ -6,8 +9,8 @@ class SlotsReservation < ApplicationRecord
   # when the SlotsReservation is deleted (from Reservation destroy cascade), we delete the
   # corresponding slot
   def cleanup_slots
-    unless slot.destroying
-      slot.destroy
-    end
+    return unless slot.destroying
+
+    slot.destroy
   end
 end

app/models/space.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# Space is a reservable item that can be booked by multiple people on the same Slot.
+# It represents a physical place, in the Fablab, like a meeting room where multiple people will be able to work at
+# the same time.
 class Space < ApplicationRecord
   extend FriendlyId
   friendly_id :name, use: :slugged

app/models/space_file.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# SpaceFile is a file stored on the file system, associated with a Space.
 class SpaceFile < Asset
   mount_uploader :attachment, SpaceFileUploader
 end

app/models/space_image.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 
+# SpaceImage is the main picture for a Space
 class SpaceImage < Asset
   mount_uploader :attachment, SpaceImageUploader
 end

app/models/spaces_availability.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# SpacesAvailability is the relation table between a Space and an Availability.
+# It defines periods in the agenda, when the given space can be reserved by members.
 class SpacesAvailability < ApplicationRecord
   belongs_to :space
   belongs_to :availability
@@ -7,8 +11,8 @@ class SpacesAvailability < ApplicationRecord
   # availability. We don't use 'dependent: destroy' as we need to prevent conflicts if the destroy came from
   # the Availability destroy cascade.
   def cleanup_availability
-    unless availability.destroying
-      availability.safe_destroy
-    end
+    return unless availability.destroying
+
+    availability.safe_destroy
   end
 end

app/models/statistic_custom_aggregation.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# StatisticCustomAggregation is an ElasticSearch aggregation that will run when the end-user is browsing the statistics
+# page for the related statisticType.
+# See https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html
 class StatisticCustomAggregation < ApplicationRecord
   belongs_to :statistic_type
 end