update API doc required params - 5

- Discussion topics
- Enrollment terms
- Enrollments
- External tools
- Favorites

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

Refs SIS-403

Change-Id: I5a926cf36f0852c11356719f76b5b54bd25f96da
Reviewed-on: https://gerrit.instructure.com/38805
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/discussion_topics_api_controller.rb

@@ -141,7 +141,7 @@ class DiscussionTopicsApiController < ApplicationController
   #
   # @argument message [String] The body of the entry.
   #
-  # @argument attachment [Optional] a multipart/form-data form-field-style
+  # @argument attachment a multipart/form-data form-field-style
   #   attachment. Attachments larger than 1 kilobyte are subject to quota
   #   restrictions.
   #
@@ -253,7 +253,7 @@ class DiscussionTopicsApiController < ApplicationController
   #
   # @argument message [String] The body of the entry.
   #
-  # @argument attachment [Optional] a multipart/form-data form-field-style
+  # @argument attachment a multipart/form-data form-field-style
   #   attachment. Attachments larger than 1 kilobyte are subject to quota
   #   restrictions.
   #
@@ -406,7 +406,7 @@ class DiscussionTopicsApiController < ApplicationController
   #
   # No request fields are necessary.
   #
-  # @argument forced_read_state [Optional, Boolean]
+  # @argument forced_read_state [Boolean]
   #   A boolean value to set all of the entries' forced_read_state. No change
   #   is made if this argument is not specified.
   # 
@@ -427,7 +427,7 @@ class DiscussionTopicsApiController < ApplicationController
   #
   # No request fields are necessary.
   #
-  # @argument forced_read_state [Optional, Boolean]
+  # @argument forced_read_state [Boolean]
   #   A boolean value to set all of the entries' forced_read_state. No change is
   #   made if this argument is not specified.
   # 
@@ -447,7 +447,7 @@ class DiscussionTopicsApiController < ApplicationController
   #
   # No request fields are necessary.
   #
-  # @argument forced_read_state [Optional, Boolean]
+  # @argument forced_read_state [Boolean]
   #   A boolean value to set the entry's forced_read_state. No change is made if
   #   this argument is not specified.
   #
@@ -468,7 +468,7 @@ class DiscussionTopicsApiController < ApplicationController
   #
   # No request fields are necessary.
   #
-  # @argument forced_read_state [Optional, Boolean]
+  # @argument forced_read_state [Boolean]
   #   A boolean value to set the entry's forced_read_state. No change is made if
   #   this argument is not specified.
   #

app/controllers/discussion_topics_controller.rb

@@ -14,7 +14,7 @@
 #
 # You should have received a copy of the GNU Affero General Public License along
 # with this program. If not, see <http://www.gnu.org/licenses/>.
-#
+
 # @API Discussion Topics
 #
 # @model FileAttachment
@@ -228,19 +228,19 @@ class DiscussionTopicsController < ApplicationController
   #
   # Returns the paginated list of discussion topics for this course or group.
   #
-  # @argument order_by [Optional, String, "position"|"recent_activity"]
+  # @argument order_by [String, "position"|"recent_activity"]
   #   Determines the order of the discussion topic list. Defaults to "position".
   #
-  # @argument scope [Optional, String, "locked"|"unlocked"|"pinned"|"unpinned"]
+  # @argument scope [String, "locked"|"unlocked"|"pinned"|"unpinned"]
   #   Only return discussion topics in the given state(s). Defaults to including
   #   all topics. Filtering is done after pagination, so pages
   #   may be smaller than requested if topics are filtered.
   #   Can pass multiple states as comma separated string.
   #
-  # @argument only_announcements [Optional, Boolean]
+  # @argument only_announcements [Boolean]
   #   Return announcements instead of discussion topics. Defaults to false
   #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
   #   The partial title of the discussion topics to match and return.
   #
   # @example_request
@@ -493,25 +493,25 @@ class DiscussionTopicsController < ApplicationController
   #
   # @argument message [String]
   #
-  # @argument discussion_type [Optional, String, "side_comment"|"threaded"]
+  # @argument discussion_type [String, "side_comment"|"threaded"]
   #   The type of discussion. Defaults to side_comment if not value is given. Accepted values are 'side_comment', for discussions that only allow one level of nested comments, and 'threaded' for fully threaded discussions.
   #
-  # @argument published [Optional, Boolean]
+  # @argument published [Boolean]
   #   Whether this topic is published (true) or draft state (false). Only
   #   teachers and TAs have the ability to create draft state topics.
   #
-  # @argument delayed_post_at [Optional, DateTime]
+  # @argument delayed_post_at [DateTime]
   #   If a timestamp is given, the topic will not be published until that time.
   #
-  # @argument lock_at [Optional, DateTime]
+  # @argument lock_at [DateTime]
   #   If a timestamp is given, the topic will be scheduled to lock at the
   #   provided timestamp. If the timestamp is in the past, the topic will be
   #   locked.
   #
-  # @argument podcast_enabled [Optional, Boolean]
+  # @argument podcast_enabled [Boolean]
   #   If true, the topic will have an associated podcast feed.
   #
-  # @argument podcast_has_student_posts [Optional, Boolean]
+  # @argument podcast_has_student_posts [Boolean]
   #   If true, the podcast will include posts from students as well. Implies
   #   podcast_enabled.
   #
@@ -519,7 +519,7 @@ class DiscussionTopicsController < ApplicationController
   #   If true then a user may not respond to other replies until that user has
   #   made an initial reply. Defaults to false.
   #
-  # @argument assignment [Optional, Assignment]
+  # @argument assignment [Assignment]
   #   To create an assignment discussion, pass the assignment parameters as a
   #   sub-object. See the {api:AssignmentsApiController#create Create an Assignment API}
   #   for the available parameters. The name parameter will be ignored, as it's
@@ -527,17 +527,17 @@ class DiscussionTopicsController < ApplicationController
   #   an assignment NOT an assignment, pass set_assignment = false as part of
   #   the assignment object
   #
-  # @argument is_announcement [Optional, Boolean]
+  # @argument is_announcement [Boolean]
   #   If true, this topic is an announcement. It will appear in the
   #   announcement's section rather than the discussions section. This requires
   #   announcment-posting permissions.
   #
-  # @argument position_after [Optional, String]
+  # @argument position_after [String]
   #   By default, discussions are sorted chronologically by creation date, you
   #   can pass the id of another topic to have this one show up after the other
   #   when they are listed.
   #
-  # @argument group_category_id [Optional, Integer]
+  # @argument group_category_id [Integer]
   #   If present, the topic will become a group discussion assigned
   #   to the group.
   #
@@ -623,7 +623,7 @@ class DiscussionTopicsController < ApplicationController
   # Puts the pinned discussion topics in the specified order.
   # All pinned topics should be included.
   #
-  # @argument order[] [Optional, Integer]
+  # @argument order[] [Required, Integer]
   #   The ids of the pinned discussion topics in the desired order.
   #   (For example, "order=104,102,103".)
   #

app/controllers/enrollments_api_controller.rb

@@ -253,7 +253,7 @@ class EnrollmentsApiController < ApplicationController
   # @API Enrollment by ID
   # Get an Enrollment object by Enrollment ID
   #
-  # @argument id [Integer]
+  # @argument id [Required, Integer]
   #  The ID of the enrollment object
   # @returns Enrollment
 
@@ -267,36 +267,36 @@ class EnrollmentsApiController < ApplicationController
   # @API Enroll a user
   # Create a new user enrollment for a course or section.
   #
-  # @argument enrollment[user_id] [String]
+  # @argument enrollment[user_id] [Required, String]
   #   The ID of the user to be enrolled in the course.
   #
-  # @argument enrollment[type] [String, "StudentEnrollment"|"TeacherEnrollment"|"TaEnrollment"|"ObserverEnrollment"|"DesignerEnrollment"]
+  # @argument enrollment[type] [Required, String, "StudentEnrollment"|"TeacherEnrollment"|"TaEnrollment"|"ObserverEnrollment"|"DesignerEnrollment"]
   #   Enroll the user as a student, teacher, TA, observer, or designer. If no
   #   value is given, the type will be inferred by enrollment[role] if supplied,
   #   otherwise 'StudentEnrollment' will be used.
   #
-  # @argument enrollment[role] [Optional, String]
+  # @argument enrollment[role] [String]
   #   Assigns a custom course-level role to the user.
   #
-  # @argument enrollment[enrollment_state] [Optional, String, "active"|"invited"]
+  # @argument enrollment[enrollment_state] [String, "active"|"invited"]
   #   If set to 'active,' student will be immediately enrolled in the course.
   #   Otherwise they will be required to accept a course invitation. Default is
   #   'invited.'
   #
-  # @argument enrollment[course_section_id] [Optional, Integer]
+  # @argument enrollment[course_section_id] [Integer]
   #   The ID of the course section to enroll the student in. If the
   #   section-specific URL is used, this argument is redundant and will be
   #   ignored.
   #
-  # @argument enrollment[limit_privileges_to_course_section] [Optional, Boolean]
+  # @argument enrollment[limit_privileges_to_course_section] [Boolean]
   #   If a teacher or TA enrollment, teacher/TA will be restricted to the
   #   section given by course_section_id.
   #
-  # @argument enrollment[notify] [Optional, Boolean]
+  # @argument enrollment[notify] [Boolean]
   #   If true, a notification will be sent to the enrolled user.
   #   Notifications are not sent by default.
   #
-  # @argument enrollment[self_enrollment_code] [Optional, String]
+  # @argument enrollment[self_enrollment_code] [String]
   #   If the current user is not allowed to manage enrollments in this
   #   course, but the course allows self-enrollment, the user can self-
   #   enroll as a student in the default section by passing in a valid

app/controllers/external_tools_controller.rb

@@ -38,7 +38,7 @@ class ExternalToolsController < ApplicationController
   # Returns the paginated list of external tools for the current context.
   # See the get request docs for a single tool for a list of properties on an external tool.
   #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
   #   The partial name of the tools to match and return.
   #
   # @example_response
@@ -136,16 +136,16 @@ class ExternalToolsController < ApplicationController
   #
   # Either the id or url must be provided.
   #
-  # @argument id [Optional, String]
+  # @argument id [String]
   #   The external id of the tool to launch.
   #
-  # @argument url [Optional, String]
+  # @argument url [String]
   #   The LTI launch url for the external tool.
   #
-  # @argument assignment_id [Optional, String]
+  # @argument assignment_id [String]
   #   The assignment id for an assignment launch.
   #
-  # @argument launch_type [Optional, String]
+  # @argument launch_type [String]
   #   The type of launch to perform on the external tool.
   #
   # @response_field id The id for the external tool to be launched.
@@ -393,116 +393,116 @@ class ExternalToolsController < ApplicationController
   # Create an external tool in the specified course/account.
   # The created tool will be returned, see the "show" endpoint for an example.
   #
-  # @argument name [String]
+  # @argument name [Required, String]
   #   The name of the tool
   #
-  # @argument privacy_level [String, "anonymous"|"name_only"|"public"]
+  # @argument privacy_level [Required, String, "anonymous"|"name_only"|"public"]
   #   What information to send to the external tool.
   #
-  # @argument consumer_key [String]
+  # @argument consumer_key [Required, String]
   #   The consumer key for the external tool
   #
-  # @argument shared_secret [String]
+  # @argument shared_secret [Required, String]
   #   The shared secret with the external tool
   #
-  # @argument description [Optional, String]
+  # @argument description [String]
   #   A description of the tool
   #
-  # @argument url [Optional, String]
+  # @argument url [String]
   #   The url to match links against. Either "url" or "domain" should be set,
   #   not both.
   #
-  # @argument domain [Optional, String]
+  # @argument domain [String]
   #   The domain to match links against. Either "url" or "domain" should be
   #   set, not both.
   #
-  # @argument icon_url [Optional, String]
+  # @argument icon_url [String]
   #   The url of the icon to show for this tool
   #
-  # @argument text [Optional, String]
+  # @argument text [String]
   #   The default text to show for this tool
   #
-  # @argument custom_fields [Optional, String]
+  # @argument custom_fields [String]
   #   Custom fields that will be sent to the tool consumer, specified as
   #   custom_fields[field_name]
   #
-  # @argument account_navigation[url] [Optional, String]
+  # @argument account_navigation[url] [String]
   #   The url of the external tool for account navigation
   #
-  # @argument account_navigation[enabled] [Optional, Boolean]
+  # @argument account_navigation[enabled] [Boolean]
   #   Set this to enable this feature
   #
-  # @argument account_navigation[text] [Optional, String]
+  # @argument account_navigation[text] [String]
   #   The text that will show on the left-tab in the account navigation
   #
-  # @argument user_navigation[url] [Optional, String]
+  # @argument user_navigation[url] [String]
   #   The url of the external tool for user navigation
   #
-  # @argument user_navigation[enabled] [Optional, Boolean]
+  # @argument user_navigation[enabled] [Boolean]
   #   Set this to enable this feature
   #
-  # @argument user_navigation[text] [Optional, String]
+  # @argument user_navigation[text] [String]
   #   The text that will show on the left-tab in the user navigation
   #
-  # @argument course_navigation[url] [Optional, String]
+  # @argument course_navigation[url] [String]
   #   The url of the external tool for course navigation
   #
-  # @argument course_navigation[enabled] [Optional, Boolean]
+  # @argument course_navigation[enabled] [Boolean]
   #   Set this to enable this feature
   #
-  # @argument course_navigation[text] [Optional, String]
+  # @argument course_navigation[text] [String]
   #   The text that will show on the left-tab in the course navigation
   #
-  # @argument course_navigation[visibility] [Optional, String, "admins"|"members"]
+  # @argument course_navigation[visibility] [String, "admins"|"members"]
   #   Who will see the navigation tab. "admins" for course admins, "members" for
   #   students, null for everyone
   #
-  # @argument course_navigation[default] [Optional, Boolean]
+  # @argument course_navigation[default] [Boolean]
   #   Whether the navigation option will show in the course by default or
   #   whether the teacher will have to explicitly enable it
   #
-  # @argument editor_button[url] [Optional, String]
+  # @argument editor_button[url] [String]
   #   The url of the external tool
   #
-  # @argument editor_button[enabled] [Optional, Boolean]
+  # @argument editor_button[enabled] [Boolean]
   #   Set this to enable this feature
   #
-  # @argument editor_button[icon_url] [Optional, String]
+  # @argument editor_button[icon_url] [String]
   #   The url of the icon to show in the WYSIWYG editor
   #
-  # @argument editor_button[selection_width] [Optional, String]
+  # @argument editor_button[selection_width] [String]
   #   The width of the dialog the tool is launched in
   #
-  # @argument editor_button[selection_height] [Optional, String]
+  # @argument editor_button[selection_height] [String]
   #   The height of the dialog the tool is launched in
   #
-  # @argument resource_selection[url] [Optional, String]
+  # @argument resource_selection[url] [String]
   #   The url of the external tool
   #
-  # @argument resource_selection[enabled] [Optional, Boolean]
+  # @argument resource_selection[enabled] [Boolean]
   #   Set this to enable this feature
   #
-  # @argument resource_selection[icon_url] [Optional, String]
+  # @argument resource_selection[icon_url] [String]
   #   The url of the icon to show in the module external tool list
   #
-  # @argument resource_selection[selection_width] [Optional, String]
+  # @argument resource_selection[selection_width] [String]
   #   The width of the dialog the tool is launched in
   #
-  # @argument resource_selection[selection_height] [Optional, String]
+  # @argument resource_selection[selection_height] [String]
   #   The height of the dialog the tool is launched in
   #
-  # @argument config_type [Optional, String]
+  # @argument config_type [String]
   #   Configuration can be passed in as CC xml instead of using query
   #   parameters. If this value is "by_url" or "by_xml" then an xml
   #   configuration will be expected in either the "config_xml" or "config_url"
   #   parameter. Note that the name parameter overrides the tool name provided
   #   in the xml
   #
-  # @argument config_xml [Optional, String]
+  # @argument config_xml [String]
   #   XML tool configuration, as specified in the CC xml specification. This is
   #   required if "config_type" is set to "by_xml"
   #
-  # @argument config_url [Optional, String]
+  # @argument config_url [String]
   #   URL where the server can retrieve an XML tool configuration, as specified
   #   in the CC xml specification. This is required if "config_type" is set to
   #   "by_url"

app/controllers/favorites_controller.rb

@@ -74,7 +74,7 @@ class FavoritesController < ApplicationController
   # Add a course to the current user's favorites.  If the course is already
   # in the user's favorites, nothing happens.
   #
-  # @argument id [String]
+  # @argument id [Required, String]
   #   The ID or SIS ID of the course to add.  The current user must be
   #   registered in the course.
   #
@@ -103,7 +103,7 @@ class FavoritesController < ApplicationController
   # @API Remove course from favorites
   # Remove a course from the current user's favorites.
   #
-  # @argument id [String]
+  # @argument id [Required, String]
   #   the ID or SIS ID of the course to remove
   #
   # @returns Favorite

app/controllers/terms_api_controller.rb

@@ -69,7 +69,7 @@ class TermsApiController < ApplicationController
   # requires permission to manage the account (when called on non-root
   # accounts, will be directed to the appropriate root account).
   #
-  # @argument workflow_state[] [Optional, String, 'active'| 'deleted'| 'all']
+  # @argument workflow_state[] [String, 'active'| 'deleted'| 'all']
   #   If set, only returns terms that are in the given state.
   #   Defaults to 'active'.
   #