[183] Rubocop: enable documentation cop

.rubocop.yml

@@ -116,7 +116,7 @@ RSpec/NestedGroups:
 #### Style ####
 
 Style/Documentation:
-  Enabled: false
+  Enabled: true
 
 Style/FrozenStringLiteralComment:
   Exclude:

app/controllers/application_controller.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# The base class for most controllers.
+# Manages authenticated user sessions and other auth methods.
 class ApplicationController < ActionController::Base
   helper_method :current_user, :logged_in?
 

app/controllers/dashboard_controller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# The dashboard controller serves the logged-in homepage of the app.
 class DashboardController < ApplicationController
   def index; end
 end

app/controllers/dev/accounts_controller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dev
+  # AccountsController offers login convenience for dev and test environments only.
   class AccountsController < ApplicationController
     skip_before_action :check_session_expiration
 

app/controllers/dev/sandbox_controller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dev
+  # Sandbox controller demos some USWDS components and layout.
   class SandboxController < ApplicationController
     def index; end
   end

app/controllers/evaluation_forms_controller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Controller for evaluation forms CRUD actions.
 class EvaluationFormsController < ApplicationController
   before_action -> { authorize_user('challenge_manager') }
   before_action :set_evaluation_form, only: %i[show edit update destroy]

app/controllers/evaluations_controller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Controller for evaluations CRUD actions.
 class EvaluationsController < ApplicationController
   before_action -> { authorize_user('evaluator') }
   def index; end

app/controllers/evaluators_controller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Controller for evaluators CRUD actions.
 class EvaluatorsController < ApplicationController
   before_action -> { authorize_user('challenge_manager') }
 

app/controllers/phases_controller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Controller for challenge phases CRUD actions.
 class PhasesController < ApplicationController
   before_action -> { authorize_user('challenge_manager') }
   before_action :set_phase, except: [:index]

app/controllers/sessions_controller.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# SessionsConroller manages session requests: login, logout and timeout functions.
+# This controller receives the redirect from login.gov and stores the valid user session.
 class SessionsController < ApplicationController
   before_action :check_error_result, :require_code_param, :exchange_token, only: [:result]
   skip_before_action :check_session_expiration, only: [:timeout, :destroy]

app/controllers/submissions_controller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Controller for challenge submissions CRUD actions.
 class SubmissionsController < ApplicationController
   before_action -> { authorize_user('challenge_manager') }
   before_action :set_submission, only: [:show, :update]

app/helpers/application_helper.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+# ApplicationHelper is the helper for generic helper methods.
+# Think twice before adding random stuff here.
 module ApplicationHelper
 end

app/helpers/dashboard_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# View helpers for the main dashboard templates supporting various user roles.
 module DashboardHelper
   def dashboard_cards_by_role
     {

app/helpers/evaluation_forms_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# View helpers for rendering evaluation forms.
 module EvaluationFormsHelper
   def challenge_with_phase(evaluation_form)
     challenge_phase_title(evaluation_form.challenge, evaluation_form.phase)

app/helpers/evaluators_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# View helpers for rendering users with the evaluator role.
 module EvaluatorsHelper
   def user_status(evaluator)
     if evaluator.is_a?(User)

app/helpers/navigation_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# View helpers for the top navigation bar and utility menu.
 module NavigationHelper
   def utility_menu_link(image_path, href, _alt, button_label)
     link_to(href,

app/helpers/phases_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# View helpers for challenge phases.
 module PhasesHelper
   def phase_number(challenge, phase)
     challenge.phase_ids.index(phase.id) + 1

app/helpers/submissions_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# View helpers for submissions.
 module SubmissionsHelper
   def eligible_for_evaluation?(submission)
     submission.judging_status.in?(%w[selected winner])

app/helpers/users_helper.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
+# View helpers for rendering generic users.
 module UsersHelper
 end

app/mailers/application_mailer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# The main app mailer for sending emails.
+# The app does not process inbound messages.
 class ApplicationMailer < ActionMailer::Base
   default from: "[email protected]"
   layout "mailer"

app/models/application_record.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# ApplicationRecord is the primary base class for DB backed models under app/models.
 class ApplicationRecord < ActiveRecord::Base
   primary_abstract_class
 

app/models/challenge_manager.rb

@@ -9,7 +9,6 @@
 #  user_id      :bigint
 #  revoked_at   :datetime
 #
-
 class ChallengeManager < ApplicationRecord
   belongs_to :challenge
   belongs_to :user

app/models/evaluation_criterion.rb

@@ -4,18 +4,18 @@
 #
 # Table name: evaluation_criteria
 #
-#  id                   :bigint           not null, primary key
-#  title                :string           not null
-#  description          :string           not null
-#  points_or_weight     :smallint         not null
-#  scoring_type         :integer          not null
-#  option_range_start   :smallint
-#  option_range_end     :smallint
-#  option_labels        :json             default([])
-#  evaluation_form_id   :bigint           not null
-#  created_at           :datetime         not null
-#  updated_at           :datetime         not null
-
+#  id                 :bigint           not null, primary key
+#  evaluation_form_id :bigint           not null
+#  title              :string           not null
+#  description        :string           not null
+#  points_or_weight   :integer          not null
+#  scoring_type       :integer          not null
+#  option_range_start :integer
+#  option_range_end   :integer
+#  option_labels      :json
+#  created_at         :datetime         not null
+#  updated_at         :datetime         not null
+#
 class EvaluationCriterion < ApplicationRecord
   self.table_name = 'evaluation_criteria'
 

app/models/evaluation_form.rb

@@ -5,15 +5,15 @@
 # Table name: evaluation_forms
 #
 #  id                :bigint           not null, primary key
-#  title             :string
-#  instructions      :string
-#  phase_id   :integer
+#  title             :string           not null
+#  instructions      :string           not null
 #  comments_required :boolean          default(FALSE)
 #  weighted_scoring  :boolean          default(FALSE)
-#  closing_date      :date
-#  challenge_id      :bigint
+#  closing_date      :date             not null
+#  challenge_id      :bigint           not null
 #  created_at        :datetime         not null
 #  updated_at        :datetime         not null
+#  phase_id          :bigint           not null
 #
 class EvaluationForm < ApplicationRecord
   belongs_to :challenge

app/models/evaluator_invitation.rb

@@ -10,7 +10,7 @@
 #  first_name       :string           not null
 #  last_name        :string           not null
 #  email            :string           not null
-#  last_invite_sent :datetime         not null
+#  last_invite_sent :datetime
 #  created_at       :datetime         not null
 #  updated_at       :datetime         not null
 #

app/models/evaluator_submission_assignment.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
+# == Schema Information
+#
+# Table name: evaluator_submission_assignments
+#
+#  id            :bigint           not null, primary key
+#  user_id       :bigint           not null
+#  submission_id :bigint           not null
+#  status        :integer          not null
+#  created_at    :datetime         not null
+#  updated_at    :datetime         not null
+#
 class EvaluatorSubmissionAssignment < ApplicationRecord
   belongs_to :submission
   belongs_to :evaluator, class_name: "User", foreign_key: :user_id, inverse_of: :assigned_submissions

app/models/login_gov.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+# LoginGov manages authentication with the external login.gov service
+# login.gov is a single-signon (SSO) identity provider (IdP) for GSA.
 class LoginGov
+  # helper class for errors from the LoginGov API
   class LoginApiError < StandardError
     attr_reader :status_code, :response_body
 

app/models/phase.rb

@@ -5,21 +5,19 @@
 # Table name: phases
 #
 #  id                     :bigint           not null, primary key
-#  uuid                   :uuid             not null, default: -> { "gen_random_uuid()" }
-#  title                  :string
+#  challenge_id           :bigint           not null
+#  uuid                   :uuid             not null
+#  title                  :string(255)
 #  start_date             :datetime
 #  end_date               :datetime
-#  open_to_submissions     :boolean
-#  judging_criteria        :string
-#  judging_criteria_delta  :string
-#  judging_criteria_length :integer          virtual
-#  how_to_enter            :string
-#  how_to_enter_delta      :string
-#  how_to_enter_length     :integer          virtual
-#  delete_phase            :boolean          virtual
-#  challenge_id            :bigint           not null
-#  created_at             :datetime         not null
+#  open_to_submissions    :boolean
+#  judging_criteria       :text
+#  judging_criteria_delta :text
+#  how_to_enter           :text
+#  how_to_enter_delta     :text
+#  inserted_at            :datetime         not null
 #  updated_at             :datetime         not null
+#  submissions_count      :integer          default(0), not null
 #
 class Phase < ApplicationRecord
   belongs_to :challenge

app/models/submission.rb

@@ -1,5 +1,30 @@
 # frozen_string_literal: true
 
+# == Schema Information
+#
+# Table name: submissions
+#
+#  id                      :bigint           not null, primary key
+#  submitter_id            :bigint           not null
+#  challenge_id            :bigint           not null
+#  title                   :string(255)
+#  brief_description       :text
+#  description             :text
+#  external_url            :string(255)
+#  status                  :string(255)
+#  deleted_at              :datetime
+#  inserted_at             :datetime         not null
+#  updated_at              :datetime         not null
+#  phase_id                :bigint           not null
+#  judging_status          :string(255)      default("not_selected")
+#  manager_id              :bigint
+#  terms_accepted          :boolean
+#  review_verified         :boolean
+#  description_delta       :text
+#  brief_description_delta :text
+#  pdf_reference           :string(255)
+#  comments                :text
+#
 class Submission < ApplicationRecord
   enum :status, { draft: "draft", submitted: "submitted" }
   enum :judging_status, { not_selected: "not_selected", selected: "selected", qualified: "qualified", winner: "winner" }

app/services/evaluator_management_service.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# This service handles evaluator invitation as well as adding and removing evalutors to challenge phases.
 class EvaluatorManagementService
   def initialize(challenge, phase)
     @challenge = challenge

spec/factories/evaluation_criteria.rb

@@ -1,3 +1,19 @@
+# == Schema Information
+#
+# Table name: evaluation_criteria
+#
+#  id                 :bigint           not null, primary key
+#  evaluation_form_id :bigint           not null
+#  title              :string           not null
+#  description        :string           not null
+#  points_or_weight   :integer          not null
+#  scoring_type       :integer          not null
+#  option_range_start :integer
+#  option_range_end   :integer
+#  option_labels      :json
+#  created_at         :datetime         not null
+#  updated_at         :datetime         not null
+#
 FactoryBot.define do
   factory :evaluation_criterion, class: 'EvaluationCriterion' do
     # Associations

spec/models/challenge_phases_evaluator_spec.rb

@@ -1,3 +1,14 @@
+# == Schema Information
+#
+# Table name: challenge_phases_evaluators
+#
+#  id           :bigint           not null, primary key
+#  challenge_id :bigint           not null
+#  phase_id     :bigint           not null
+#  user_id      :bigint           not null
+#  created_at   :datetime         not null
+#  updated_at   :datetime         not null
+#
 require 'rails_helper'
 
 RSpec.describe ChallengePhasesEvaluator, type: :model do

spec/models/evaluation_criterion_spec.rb

@@ -1,3 +1,19 @@
+# == Schema Information
+#
+# Table name: evaluation_criteria
+#
+#  id                 :bigint           not null, primary key
+#  evaluation_form_id :bigint           not null
+#  title              :string           not null
+#  description        :string           not null
+#  points_or_weight   :integer          not null
+#  scoring_type       :integer          not null
+#  option_range_start :integer
+#  option_range_end   :integer
+#  option_labels      :json
+#  created_at         :datetime         not null
+#  updated_at         :datetime         not null
+#
 require 'rails_helper'
 
 RSpec.describe EvaluationCriterion, type: :model do

spec/models/evaluation_form_spec.rb

@@ -3,15 +3,15 @@
 # Table name: evaluation_forms
 #
 #  id                :bigint           not null, primary key
-#  title             :string
-#  instructions      :string
-#  phase_id          :integer
+#  title             :string           not null
+#  instructions      :string           not null
 #  comments_required :boolean          default(FALSE)
 #  weighted_scoring  :boolean          default(FALSE)
-#  closing_date      :date
-#  challenge_id      :bigint
+#  closing_date      :date             not null
+#  challenge_id      :bigint           not null
 #  created_at        :datetime         not null
 #  updated_at        :datetime         not null
+#  phase_id          :bigint           not null
 #
 require 'rails_helper'