update API doc required params - 6

- Feature flags
- Files
- Grade change log
- Gradebook history
- Grading standards

Test plan:
- rake doc:api
- Verify the above doc pages for parameter accuracy

Refs SIS-403

Change-Id: I52627a9bd557682c12713455e989d2e054c744b6
Reviewed-on: https://gerrit.instructure.com/38808
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Tyler Pickett <tpickett+gerrit@instructure.com>
Product-Review: Tyler Pickett <tpickett+gerrit@instructure.com>
QA-Review: Jeremy Putnam <jeremyp@instructure.com>

app/controllers/feature_flags_controller.rb

@@ -206,13 +206,13 @@ class FeatureFlagsController < ApplicationController
   # Set a feature flag for a given Account, Course, or User. This call will fail if a parent account sets
   # a feature flag for the same feature in any state other than "allowed".
   #
-  # @argument state [Optional, String, "off"|"allowed"|"on"]
+  # @argument state [String, "off"|"allowed"|"on"]
   #   "off":: The feature is not available for the course, user, or account and sub-accounts.
   #   "allowed":: (valid only on accounts) The feature is off in the account, but may be enabled in
   #               sub-accounts and courses by setting a feature flag on the sub-account or course.
   #   "on":: The feature is turned on unconditionally for the user, course, or account and sub-accounts.
   #
-  # @argument locking_account_id [Optional, Integer]
+  # @argument locking_account_id [Integer]
   #   If set, this FeatureFlag may only be modified by someone with administrative rights
   #   in the specified account. The locking account must be above the target object in the
   #   account chain.

app/controllers/files_controller.rb

@@ -207,23 +207,23 @@ class FilesController < ApplicationController
   # @API List files
   # Returns the paginated list of files for the folder or course.
   #
-  # @argument content_types[] [Optional, String]
+  # @argument content_types[] [String]
   #   Filter results by content-type. You can specify type/subtype pairs (e.g.,
   #   'image/jpeg'), or simply types (e.g., 'image', which will match
   #   'image/gif', 'image/jpeg', etc.).
   #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
   #   The partial name of the files to match and return.
   #
-  # @argument include[] [Optional, "user"]
+  # @argument include[] ["user"]
   #   Array of additional information to include.
   #
   #   "user":: the user who uploaded the file or last edited its content
   #
-  # @argument sort [Optional, String, "name"|"size"|"created_at"|"updated_at"|"content_type"|"user"]
+  # @argument sort [String, "name"|"size"|"created_at"|"updated_at"|"content_type"|"user"]
   #   Sort results by this field. Defaults to 'name'. Note that `sort=user` implies `include[]=user`.
   #
-  # @argument order [Optional, String, "asc"|"desc"]
+  # @argument order [String, "asc"|"desc"]
   #   The sorting order. Defaults to 'asc'.
   #
   # @example_request
@@ -412,7 +412,7 @@ class FilesController < ApplicationController
   # @API Get file
   # Returns the standard attachment json object
   #
-  # @argument include[] [Optional, "user"]
+  # @argument include[] ["user"]
   #   Array of additional information to include.
   #
   #   "user":: the user who uploaded the file or last edited its content

app/controllers/folders_controller.rb

@@ -365,7 +365,7 @@ class FoldersController < ApplicationController
   # @subtopic Folders
   # Creates a folder in the specified context
   #
-  # @argument name [String]
+  # @argument name [Required, String]
   #   The name of the folder
   #
   # @argument parent_folder_id [String]

app/controllers/grade_change_audit_api_controller.rb

@@ -115,10 +115,10 @@ class GradeChangeAuditApiController < AuditorApiController
   #
   # List grade change events for a given assignment.
   #
-  # @argument start_time [Optional, DateTime]
+  # @argument start_time [DateTime]
   #   The beginning of the time range from which you want events.
   #
-  # @argument end_time [Optional, Datetime]
+  # @argument end_time [Datetime]
   #   The end of the time range from which you want events.
   #
   # @returns [GradeChangeEvent]
@@ -140,10 +140,10 @@ class GradeChangeAuditApiController < AuditorApiController
   #
   # List grade change events for a given course.
   #
-  # @argument start_time [Optional, DateTime]
+  # @argument start_time [DateTime]
   #   The beginning of the time range from which you want events.
   #
-  # @argument end_time [Optional, Datetime]
+  # @argument end_time [Datetime]
   #   The end of the time range from which you want events.
   #
   # @returns [GradeChangeEvent]
@@ -162,10 +162,10 @@ class GradeChangeAuditApiController < AuditorApiController
   #
   # List grade change events for a given student.
   #
-  # @argument start_time [Optional, DateTime]
+  # @argument start_time [DateTime]
   #   The beginning of the time range from which you want events.
   #
-  # @argument end_time [Optional, Datetime]
+  # @argument end_time [Datetime]
   #   The end of the time range from which you want events.
   #
   # @returns [GradeChangeEvent]
@@ -187,10 +187,10 @@ class GradeChangeAuditApiController < AuditorApiController
   #
   # List grade change events for a given grader.
   #
-  # @argument start_time [Optional, DateTime]
+  # @argument start_time [DateTime]
   #   The beginning of the time range from which you want events.
   #
-  # @argument end_time [Optional, Datetime]
+  # @argument end_time [Datetime]
   #   The end of the time range from which you want events.
   #
   # @returns [GradeChangeEvent]

app/controllers/gradebook_history_api_controller.rb

@@ -215,7 +215,7 @@
   # @API Days in gradebook history for this course
   # Returns a map of dates to grader/assignment groups
   #
-  # @argument course_id [Integer]
+  # @argument course_id [Required, Integer]
   #   The id of the contextual course for this API call
   #
   # @returns [Day]
@@ -229,10 +229,10 @@
   # More details can be obtained by selecting a grader and assignment and calling the
   # 'submissions' api endpoint for a given date.
   #
-  # @argument course_id [Integer]
+  # @argument course_id [Required, Integer]
   #   The id of the contextual course for this API call
   #
-  # @argument date [String]
+  # @argument date [Required, String]
   #   The date for which you would like to see detailed information
   #
   # @returns [Grader]
@@ -246,16 +246,16 @@
   # @API Lists submissions
   # Gives a nested list of submission versions
   #
-  # @argument course_id [Integer]
+  # @argument course_id [Required, Integer]
   #   The id of the contextual course for this API call
   #
-  # @argument date [String]
+  # @argument date [Required, String]
   #   The date for which you would like to see submissions
   #
-  # @argument grader_id [Integer]
+  # @argument grader_id [Required, Integer]
   #   The ID of the grader for which you want to see submissions
   #
-  # @argument assignment_id [Integer]
+  # @argument assignment_id [Required, Integer]
   #   The ID of the assignment for which you want to see submissions
   #
   # @returns [SubmissionHistory]
@@ -273,19 +273,19 @@
   # the +new_grade+ or +previous_grade+ keys, only the +grade+; same for
   # +graded_at+ and +grader+.
   #
-  # @argument course_id [Integer]
+  # @argument course_id [Required, Integer]
   #   The id of the contextual course for this API call
   #
-  # @argument assignment_id [Optional, Integer]
+  # @argument assignment_id [Integer]
   #   The ID of the assignment for which you want to see submissions. If
   #   absent, versions of submissions from any assignment in the course are
   #   included.
   #
-  # @argument user_id [Optional, Integer]
+  # @argument user_id [Integer]
   #   The ID of the user for which you want to see submissions. If absent,
   #   versions of submissions from any user in the course are included.
   #
-  # @argument ascending [Optional, Boolean]
+  # @argument ascending [Boolean]
   #   Returns submission versions in ascending date order (oldest first). If
   #   absent, returns submission versions in descending date order (newest
   #   first).

app/controllers/grading_standards_api_controller.rb

@@ -94,14 +94,14 @@ class GradingStandardsApiController < ApplicationController
   #      "D-" : 61,
   #      "F" : 0,
   #
-  # @argument title [String]
+  # @argument title [Required, String]
   #   The title for the Grading Standard.
   #
-  # @argument grading_scheme_entry[][name] [String]
+  # @argument grading_scheme_entry[][name] [Required, String]
   #   The name for an entry value within a GradingStandard that describes the range of the value
   #   e.g. A-
   #
-  # @argument grading_scheme_entry[][value] [Integer]
+  # @argument grading_scheme_entry[][value] [Required, Integer]
   #   The value for the name of the entry within a GradingStandard.
   #   The entry represents the lower bound of the range for the entry.
   #   This range includes the value up to the next entry in the GradingStandard,