WIP: Validation and documentation

.gitignore

@@ -18,9 +18,15 @@
 # Ignore all logfiles and tempfiles.
 /log/*
 /tmp/*
+/doc_gen/*
 !/log/.keep
 !/tmp/.keep
+!/doc_gen/.keep
 public/assets/*
+.yardoc
 
 # Ignore Byebug command history file.
 .byebug_history
+
+# Ignore IDEA
+.idea

.yardopts

@@ -0,0 +1 @@
+--output-dir doc_gen

Gemfile

@@ -37,6 +37,9 @@ gem 'haml'
 # Use Fontawesome icons
 gem 'font-awesome-sass'
 
+# Use YARD for documentation
+gem 'yard'
+
 # Use Capistrano for deployment
 # gem 'capistrano-rails', group: :development
 

Gemfile.lock

@@ -159,6 +159,7 @@ GEM
     websocket-driver (0.6.4)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.2)
+    yard (0.9.5)
 
 PLATFORMS
   ruby
@@ -184,6 +185,7 @@ DEPENDENCIES
   tzinfo-data
   uglifier (>= 1.3.0)
   web-console
+  yard
 
 BUNDLED WITH
    1.13.6

app/models/activity.rb

@@ -1,4 +1,48 @@
+# An Activity represents a single continuous event that the members of a group may attend.
+# An Activity belongs to a group, and has many participants.
 class Activity < ApplicationRecord
+  # @!attribute public_name
+  #   @return [String]
+  #     the name that users will see if there is no {#secret_name}, or if
+  #     {#show_hidden} is `false`.
+  #
+  # @!attribute secret_name
+  #   @return [String]
+  #     a name that is (be default) only visible to organizers and group
+  #     leaders.  Can be shown or hidden to normal participants using
+  #     {#show_hidden}.
+  #
+  # @!attribute description
+  #   @return [String]
+  #     a short text describing the activity. This text is always visible to
+  #     all users.
+  #
+  # @!attribute location
+  #   @return [String]
+  #     a short text describing where the activity will take place. Always
+  #     visible to all participants.
+  #
+  # @!attribute show_hidden
+  #   @return [Boolean]
+  #     Whether or not the 'secret' attributes can be viewed by the people who
+  #     aren't organizers or group leaders. Currently, only {#secret_name} is
+  #     influenced by this. More attributes may be added in the future, and
+  #     will be controlled by this toggle as well.
+  #
+  # @!attribute start
+  #   @return [TimeWithZone]
+  #     when the activity starts.
+  #
+  # @!attribute end
+  #   @return [TimeWithZone]
+  #     when the activity ends.
+  #
+  # @!attribute deadline
+  #   @return [TimeWithZone]
+  #     when the normal participants (everyone who isn't an organizer or group
+  #     leader) may not change their own attendance anymore. Disabled if set to
+  #     nil.
+
   belongs_to :group
 
   has_many :participants
@@ -6,20 +50,45 @@ class Activity < ApplicationRecord
 
   validates :public_name, presence: true
   validates :start, presence: true
-  validate  :deadline_before_start
+  validate  :deadline_before_start, unless: "self.deadline.blank?"
+  validate  :end_after_start,       unless: "self.end.blank?"
 
+  # Get all people (not participants) that are organizers. Does not include
+  # group leaders, although they may modify the activity as well.
   def organizers
-    self.organizers.includes(:person).where(is_organizer: true)
+    self.participants.includes(:person).where(is_organizer: true)
+  end
+
+  # Determine whether the passed Person participates in the activity.
+  def is_participant?(person)
+    Participant.exists?(
+      activity_id: self.id,
+      person_id: person.id
+    )
   end
 
-  def is_organizer(person)
-    Participant.exists?(person_id: person.id, activity_id: self.id, is_organizer: true)
+  # Determine whether the passed Person is an organizer for the activity.
+  def is_organizer?(person)
+    Participant.exists?(
+      person_id: person.id,
+      activity_id: self.id,
+      is_organizer: true
+    )
   end
 
   private
+  # Assert that the deadline for participants to change the deadline, if any,
+  # is set before the event starts.
   def deadline_before_start
-    if self.deadline && self.deadline > self.start
+    if self.deadline > self.start
       errors.add(:deadline, 'must be before start')
     end
   end
+
+  # Assert that the activity's end, if any, occurs after the event's start.
+  def end_after_start
+    if self.end < self.start
+      errors.add(:end, 'must be after start')
+    end
+  end
 end

app/models/group.rb

@@ -1,10 +1,24 @@
+# A Group contains Members, which can organize and participate in Activities.
+# Some of the Members may be group leaders, with the ability to see all
+# information and add or remove members from the group.
 class Group < ApplicationRecord
+  # @!attribute name
+  #   @return [String]
+  #     the name of the group. Must be unique across all groups.
+
   has_many :members
   has_many :people, through: :members
 
   has_many :activities
 
+  validates :name,
+    presence: true,
+    uniqueness: {
+      case_sensitive: false
+    }
+
+  # @return [Array<Member>] the members in the group who are also group leaders.
   def leaders
-    self.members.where(is_leader: true)
+    self.members.includes(:person).where(is_leader: true)
   end
 end

app/models/member.rb

@@ -1,4 +1,16 @@
+# A Member represents the many-to-many relation of Groups to People. At most
+# one member may exist for each Person-Group combination.
 class Member < ApplicationRecord
+  # @!attribute is_leader
+  #   @return [Boolean]
+  #     whether the person is a leader in the group.
+
   belongs_to :person
   belongs_to :group
+
+  validates :person_id,
+    uniqueness: {
+      scope: :group_id,
+      message: "is already a member of this group"
+    }
 end

app/models/participant.rb

@@ -1,4 +1,26 @@
+# A Participant represents the many-to-many relation between People and
+# Activities, and contains the information on whether or not the person plans
+# to be present at the activity.
 class Participant < ApplicationRecord
+  # @!attribute is_organizer
+  #   @return [Boolean]
+  #     whether the person is an organizer for this event.
+  #
+  # @!attribute attending
+  #   @return [Boolean]
+  #     whether or not the person plans to attend the activity.
+  #
+  # @!attribute notes
+  #   @return [String]
+  #     a short text indicating any irregularities, such as arriving later or
+  #     leaving earlier.
+
   belongs_to :person
   belongs_to :activity
+
+  validates :person_id,
+    uniqueness: {
+      scope: :activity_id,
+      message: "person already participates in this activity"
+    }
 end

app/models/person.rb

@@ -1,4 +1,33 @@
+# A person represents a human being. A Person may be a Member in one or more
+# Groups, and be a Participant in any number of events of those Groups.
+# A Person may access the system by creating a User, and may have at most one
+# User.
 class Person < ApplicationRecord
+  # @!attribute first_name
+  #   @return [String]
+  #     the person's first name. ('Vincent' in 'Vincent van Gogh'.)
+  #
+  # @!attribute infix
+  #   @return [String]
+  #     the part of a person's surname that is not taken into account when
+  #     sorting by surname. ('van' in 'Vincent van Gogh'.)
+  #
+  # @!attribute last_name
+  #   @return [String]
+  #     the person's surname. ('Gogh' in 'Vincent van Gogh'.)
+  #
+  # @!attribute birth_date
+  #   @return [Date]
+  #     the person's birth date.
+  #
+  # @!attribute email
+  #   @return [String]
+  #     the person's email address.
+  #
+  # @!attribute is_admin
+  #   @return [Boolean]
+  #     whether or not the person has administrative rights.
+
   has_one :user
   has_many :members
   has_many :participants
@@ -14,6 +43,7 @@ class Person < ApplicationRecord
   before_validation :not_admin_if_nil
   before_save :update_user_email, if: :email_changed?
 
+  # The person's full name.
   def full_name
     if self.infix
       [self.first_name, self.infix, self.last_name].join(' ')
@@ -22,6 +52,7 @@ class Person < ApplicationRecord
     end
   end
 
+  # The person's reversed name, to sort by surname.
   def reversed_name
     if self.infix
       [self.last_name, self.infix, self.first_name].join(', ')
@@ -30,17 +61,26 @@ class Person < ApplicationRecord
     end
   end
 
+  # All activities where this person is an organizer.
+  def organized_activities
+    self.participants.includes(:activity).where(is_leader: true)
+  end
+
   private
+  # Assert that the person's birth date, if any, lies in the past.
   def birth_date_cannot_be_in_future
     if self.birth_date && self.birth_date > Date.today
       errors.add(:birth_date, "can't be in the future.")
     end
   end
 
+  # Explicitly force nil to false in the admin field.
   def not_admin_if_nil
     self.is_admin ||= false
   end
 
+  # Ensure the person's user email is updated at the same time as the person's
+  # email.
   def update_user_email
     if not self.user.nil?
       self.user.update!(email: self.email)

app/models/user.rb

@@ -1,4 +1,11 @@
+# A User contains the login information for a single Person, and allows the
+# user to log in by creating Sessions.
 class User < ApplicationRecord
+  # @!attribute email
+  #   @return [String]
+  #     the user's email address. Should be the same as the associated Person's
+  #     email address.
+
   has_secure_password
   belongs_to :person
 
@@ -8,6 +15,8 @@ class User < ApplicationRecord
   before_validation :email_same_as_person
 
   private
+  # Assert that the user's email address is the same as the email address of
+  # the associated Person.
   def email_same_as_person
     if self.person and self.email != self.person.email
       errors.add(:email, "must be the same as associated person's email")

db/migrate/20161231185937_enforce_many_to_many_uniqueness.rb

@@ -0,0 +1,9 @@
+class EnforceManyToManyUniqueness < ActiveRecord::Migration[5.0]
+  def change
+    add_index :participants, [:person_id, :activity_id], unique: true
+    add_index :members,      [:person_id, :group_id],    unique: true
+
+    remove_index :users, [:person_id]
+    add_index    :users, [:person_id], unique: true
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 20161214112504) do
+ActiveRecord::Schema.define(version: 20161231185937) do
 
   create_table "activities", force: :cascade do |t|
     t.string   "public_name"
@@ -40,6 +40,7 @@ ActiveRecord::Schema.define(version: 20161214112504) do
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
     t.index ["group_id"], name: "index_members_on_group_id"
+    t.index ["person_id", "group_id"], name: "index_members_on_person_id_and_group_id", unique: true
     t.index ["person_id"], name: "index_members_on_person_id"
   end
 
@@ -52,6 +53,7 @@ ActiveRecord::Schema.define(version: 20161214112504) do
     t.datetime "created_at",   null: false
     t.datetime "updated_at",   null: false
     t.index ["activity_id"], name: "index_participants_on_activity_id"
+    t.index ["person_id", "activity_id"], name: "index_participants_on_person_id_and_activity_id", unique: true
     t.index ["person_id"], name: "index_participants_on_person_id"
   end
 
@@ -87,7 +89,7 @@ ActiveRecord::Schema.define(version: 20161214112504) do
     t.datetime "created_at",           null: false
     t.datetime "updated_at",           null: false
     t.index ["email"], name: "index_users_on_email", unique: true
-    t.index ["person_id"], name: "index_users_on_person_id"
+    t.index ["person_id"], name: "index_users_on_person_id", unique: true
   end
 
 end