update API doc required params - 7

- Group categories - Groups - Live assessments - Logins - Modules Test plan: - rake doc:api - Verify the above doc pages for parameter accuracy Refs SIS-403 Change-Id: If70ac7240171a88dcc0e1f54c1ae12a4b0a35f6f Reviewed-on: https://gerrit.instructure.com/39021 Tested-by: Jenkins <jenkins@instructure.com> QA-Review: Jeremy Putnam <jeremyp@instructure.com> Reviewed-by: Tyler Pickett <tpickett+gerrit@instructure.com> Product-Review: Tyler Pickett <tpickett+gerrit@instructure.com>
2014-08-11 08:08:38 -06:00 · 2014-08-11 08:08:38 -06:00 · c630c2776a
parent 673dd0165d
commit c630c2776a
7 changed files with 63 additions and 63 deletions
--- a/app/controllers/context_module_items_api_controller.rb
+++ b/app/controllers/context_module_items_api_controller.rb
@ -209,10 +209,10 @@ class ContextModuleItemsApiController < ApplicationController
  #   Item specification} for more details.
  #   Includes standard lock information for each item.
  #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
  #   The partial title of the items to match and return.
  #
-  # @argument student_id [Optional]
+  # @argument student_id
  #   Returns module completion information for the student with this id.
  #
  # @example_request
@ -243,7 +243,7 @@ class ContextModuleItemsApiController < ApplicationController
  #   Item specification} for more details.
  #   Includes standard lock information for each item.
  #
-  # @argument student_id [Optional]
+  # @argument student_id
  #   Returns module completion information for the student with this id.
  #
  # @example_request
@ -281,20 +281,20 @@ class ContextModuleItemsApiController < ApplicationController
  #
  # Create and return a new module item
  #
-  # @argument module_item[title] [Optional, String]
+  # @argument module_item[title] [String]
  #   The name of the module item and associated content
  #
-  # @argument module_item[type] [String, "File"|"Page"|"Discussion"|"Assignment"|"Quiz"|"SubHeader"|"ExternalUrl"|"ExternalTool"]
+  # @argument module_item[type] [Required, String, "File"|"Page"|"Discussion"|"Assignment"|"Quiz"|"SubHeader"|"ExternalUrl"|"ExternalTool"]
  #   The type of content linked to the item
  #
-  # @argument module_item[content_id] [String]
+  # @argument module_item[content_id] [Required, String]
  #   The id of the content to link to the module item. Required, except for
  #   'ExternalUrl', 'Page', and 'SubHeader' types.
  #
-  # @argument module_item[position] [Optional, Integer]
+  # @argument module_item[position] [Integer]
  #   The position of this item in the module (1-based).
  #
-  # @argument module_item[indent] [Optional, Integer]
+  # @argument module_item[indent] [Integer]
  #   0-based indent level; module items may be indented to show a hierarchy
  #
  # @argument module_item[page_url] [String]
@ -305,11 +305,11 @@ class ContextModuleItemsApiController < ApplicationController
  #   External url that the item points to. [Required for 'ExternalUrl' and
  #   'ExternalTool' types.
  #
-  # @argument module_item[new_tab] [Optional, Boolean]
+  # @argument module_item[new_tab] [Boolean]
  #   Whether the external tool opens in a new tab. Only applies to
  #   'ExternalTool' type.
  #
-  # @argument module_item[completion_requirement][type] [Optional, String, "must_view"|"must_contribute"|"must_submit"]
+  # @argument module_item[completion_requirement][type] [String, "must_view"|"must_contribute"|"must_submit"]
  #   Completion requirement for this module item.
  #   "must_view": Applies to all item types
  #   "must_contribute": Only applies to "Assignment", "Discussion", and "Page" types
@ -373,23 +373,23 @@ class ContextModuleItemsApiController < ApplicationController
  #
  # Update and return an existing module item
  #
-  # @argument module_item[title] [Optional, String]
+  # @argument module_item[title] [String]
  #   The name of the module item
  #
-  # @argument module_item[position] [Optional, Integer]
+  # @argument module_item[position] [Integer]
  #   The position of this item in the module (1-based)
  #
-  # @argument module_item[indent] [Optional, Integer]
+  # @argument module_item[indent] [Integer]
  #   0-based indent level; module items may be indented to show a hierarchy
  #
-  # @argument module_item[external_url] [Optional, String]
+  # @argument module_item[external_url] [String]
  #   External url that the item points to. Only applies to 'ExternalUrl' type.
  #
-  # @argument module_item[new_tab] [Optional, Boolean]
+  # @argument module_item[new_tab] [Boolean]
  #   Whether the external tool opens in a new tab. Only applies to
  #   'ExternalTool' type.
  #
-  # @argument module_item[completion_requirement][type] [Optional, "must_view"|"must_contribute"|"must_submit"]
+  # @argument module_item[completion_requirement][type] [String, "must_view"|"must_contribute"|"must_submit"]
  #   Completion requirement for this module item.
  #   "must_view": Applies to all item types
  #   "must_contribute": Only applies to "Assignment", "Discussion", and "Page" types
@ -400,10 +400,10 @@ class ContextModuleItemsApiController < ApplicationController
  #   Minimum score required to complete, Required for completion_requirement
  #   type 'min_score'.
  #
-  # @argument module_item[published] [Optional, Boolean]
+  # @argument module_item[published] [Boolean]
  #   Whether the module item is published and visible to students.
  #
-  # @argument module_item[module_id] [Optional, String]
+  # @argument module_item[module_id] [String]
  #   Move this item to another module by specifying the target module id here.
  #   The target module must be in the same course.
  #
--- a/app/controllers/context_modules_api_controller.rb
+++ b/app/controllers/context_modules_api_controller.rb
@ -337,11 +337,11 @@ class ContextModulesApiController < ApplicationController
  #      details with module items specific to their associated content items.
  #      Includes standard lock information for each item.
  #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
  #   The partial name of the modules (and module items, if include['items'] is
  #   specified) to match and return.
  #
-  # @argument student_id [Optional]
+  # @argument student_id
  #   Returns module completion information for the student with this id.
  #
  # @example_request
@ -391,7 +391,7 @@ class ContextModulesApiController < ApplicationController
  #      details with module items specific to their associated content items.
  #      Includes standard lock information for each item.
  #
-  # @argument student_id [Optional]
+  # @argument student_id
  #   Returns module completion information for the student with this id.
  #
  # @example_request
@ -413,10 +413,10 @@ class ContextModulesApiController < ApplicationController
  #
  # Update multiple modules in an account.
  #
-  # @argument module_ids[] [String]
+  # @argument module_ids[] [Required, String]
  #   List of ids of modules to update.
  #
-  # @argument event [String]
+  # @argument event [Required, String]
  #   The action to take on each module. Must be 'delete'.
  #
  # @response_field completed A list of IDs for modules that were updated.
@ -468,24 +468,24 @@ class ContextModulesApiController < ApplicationController
  #
  # Create and return a new module
  #
-  # @argument module[name] [String]
+  # @argument module[name] [Required, String]
  #   The name of the module
  #
-  # @argument module[unlock_at] [Optional, DateTime]
+  # @argument module[unlock_at] [DateTime]
  #   The date the module will unlock
  #
-  # @argument module[position] [Optional, Integer]
+  # @argument module[position] [Integer]
  #   The position of this module in the course (1-based)
  #
-  # @argument module[require_sequential_progress] [Optional, Boolean]
+  # @argument module[require_sequential_progress] [Boolean]
  #   Whether module items must be unlocked in order
  #
-  # @argument module[prerequisite_module_ids][] [Optional, String]
+  # @argument module[prerequisite_module_ids][] [String]
  #   IDs of Modules that must be completed before this one is unlocked.
  #   Prerequisite modules must precede this module (i.e. have a lower position
  #   value), otherwise they will be ignored
  #
-  # @argument module[publish_final_grade] [Optional, Boolean]
+  # @argument module[publish_final_grade] [Boolean]
  #   Whether to publish the student's final grade for the course upon
  #   completion of this module.
  #
@ -530,28 +530,28 @@ class ContextModulesApiController < ApplicationController
  #
  # Update and return an existing module
  #
-  # @argument module[name] [Optional, String]
+  # @argument module[name] [String]
  #   The name of the module
  #
-  # @argument module[unlock_at] [Optional, DateTime]
+  # @argument module[unlock_at] [DateTime]
  #   The date the module will unlock
  #
-  # @argument module[position] [Optional, Integer]
+  # @argument module[position] [Integer]
  #   The position of the module in the course (1-based)
  #
-  # @argument module[require_sequential_progress] [Optional, Boolean]
+  # @argument module[require_sequential_progress] [Boolean]
  #   Whether module items must be unlocked in order
  #
-  # @argument module[prerequisite_module_ids][] [Optional, String]
+  # @argument module[prerequisite_module_ids][] [String]
  #   IDs of Modules that must be completed before this one is unlocked
  #   Prerequisite modules must precede this module (i.e. have a lower position
  #   value), otherwise they will be ignored
  #
-  # @argument module[publish_final_grade] [Optional, Boolean]
+  # @argument module[publish_final_grade] [Boolean]
  #   Whether to publish the student's final grade for the course upon
  #   completion of this module.
  #
-  # @argument module[published] [Optional, Boolean]
+  # @argument module[published] [Boolean]
  #   Whether the module is published and visible to students
  #
  # @example_request
--- a/app/controllers/group_categories_controller.rb
+++ b/app/controllers/group_categories_controller.rb
@ -146,30 +146,30 @@ class GroupCategoriesController < ApplicationController
  # @API Create a Group Category
  # Create a new group category
  #
-  # @argument name [String]
+  # @argument name [Required, String]
  #   Name of the group category
  #
-  # @argument self_signup [Optional, "enabled"|"restricted"]
+  # @argument self_signup [String, "enabled"|"restricted"]
  #   Allow students to sign up for a group themselves (Course Only).
  #   valid values are:
  #   "enabled":: allows students to self sign up for any group in course
  #   "restricted":: allows students to self sign up only for groups in the
  #                  same section null disallows self sign up
  #
-  # @argument auto_leader [Optional, "first"|"random"]
+  # @argument auto_leader [String, "first"|"random"]
  #   Assigns group leaders automatically when generating and allocating students to groups
  #   Valid values are:
  #   "first":: the first student to be allocated to a group is the leader
  #   "random":: a random student from all members is chosen as the leader
  #
-  # @argument group_limit [Optional]
+  # @argument group_limit [Integer]
  #   Limit the maximum number of users in each group (Course Only). Requires
  #   self signup.
  #
-  # @argument create_group_count [Optional]
+  # @argument create_group_count [Integer]
  #   Create this number of groups (Course Only).
  #
-  # @argument split_group_count [Optional] (Deprecated)
+  # @argument split_group_count (Deprecated)
  #   Create this number of groups, and evenly distribute students
  #   among them. not allowed with "enable_self_signup". because
  #   the group assignment happens synchronously, it's recommended
@ -204,27 +204,27 @@ class GroupCategoriesController < ApplicationController
  # @argument name [String]
  #   Name of the group category
  #
-  # @argument self_signup [Optional, "enabled"|"restricted"]
+  # @argument self_signup [String, "enabled"|"restricted"]
  #   Allow students to sign up for a group themselves (Course Only).
  #   Valid values are:
  #   "enabled":: allows students to self sign up for any group in course
  #   "restricted":: allows students to self sign up only for groups in the
  #                  same section null disallows self sign up
  #
-  # @argument auto_leader [Optional, "first"|"random"]
+  # @argument auto_leader [String, "first"|"random"]
  #   Assigns group leaders automatically when generating and allocating students to groups
  #   Valid values are:
  #   "first":: the first student to be allocated to a group is the leader
  #   "random":: a random student from all members is chosen as the leader
  #
-  # @argument group_limit [Optional]
+  # @argument group_limit [Integer]
  #   Limit the maximum number of users in each group (Course Only). Requires
  #   self signup.
  #
-  # @argument create_group_count [Optional]
+  # @argument create_group_count [Integer]
  #   Create this number of groups (Course Only).
  #
-  # @argument split_group_count [Optional] (Deprecated)
+  # @argument split_group_count (Deprecated)
  #   Create this number of groups, and evenly distribute students
  #   among them. not allowed with "enable_self_signup". because
  #   the group assignment happens synchronously, it's recommended
@ -311,11 +311,11 @@ class GroupCategoriesController < ApplicationController
  #
  # Returns a list of users in the group category.
  #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
  #   The partial name or full ID of the users to match and return in the results
  #   list. Must be at least 3 characters.
  #
-  # @argument unassigned [Optional, Boolean]
+  # @argument unassigned [Boolean]
  #   Set this value to true if you wish only to search unassigned users in the
  #   group category.
  #
@ -355,7 +355,7 @@ class GroupCategoriesController < ApplicationController
  # Assign all unassigned members as evenly as possible among the existing
  # student groups.
  #
-  # @argument sync [Optional, Boolean]
+  # @argument sync [Boolean]
  #   The assigning is done asynchronously by default. If you would like to
  #   override this and have the assigning done synchronously, set this value
  #   to true.
--- a/app/controllers/group_memberships_controller.rb
+++ b/app/controllers/group_memberships_controller.rb
@ -83,7 +83,7 @@ class GroupMembershipsController < ApplicationController
  #
  # List the members of a group.
  #
-  # @argument filter_states[] [Optional, String, "accepted"|"invited"|"requested"]
+  # @argument filter_states[] [String, "accepted"|"invited"|"requested"]
  #   Only list memberships with the given workflow_states. By default it will
  #   return all memberships.
  #
@ -144,7 +144,7 @@ class GroupMembershipsController < ApplicationController
  #
  # Accept a membership request, or add/remove moderator rights.
  #
-  # @argument workflow_state [Optional, String, "accepted"]
+  # @argument workflow_state [String, "accepted"]
  #   Currently, the only allowed value is "accepted"
  #
  # @argument moderator
--- a/app/controllers/groups_controller.rb
+++ b/app/controllers/groups_controller.rb
@ -182,7 +182,7 @@ class GroupsController < ApplicationController
  #
  # Returns a list of active groups for the current user.
  #
-  # @argument context_type [Optional, String, "Account"|"Course"]
+  # @argument context_type [String, "Account"|"Course"]
  #  Only include groups that are in this type of context.
  #
  # @example_request
@ -544,7 +544,7 @@ class GroupsController < ApplicationController
  # Sends an invitation to all supplied email addresses which will allow the
  # receivers to join the group.
  #
-  # @argument invitees[] [String]
+  # @argument invitees[] [Required, String]
  #   An array of email addresses to be sent invitations.
  #
  # @example_request
@ -609,7 +609,7 @@ class GroupsController < ApplicationController
  #
  # Returns a list of users in the group.
  #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
  #   The partial name or full ID of the users to match and return in the
  #   results list. Must be at least 3 characters.
  #
--- a/app/controllers/live_assessments/results_controller.rb
+++ b/app/controllers/live_assessments/results_controller.rb
@ -139,7 +139,7 @@ module LiveAssessments
    #
    # Returns a list of live assessment results
    #
-    # @argument user_id [Optional, Integer]
+    # @argument user_id [Integer]
    #   If set, restrict results to those for this user
    #
    # @example_response
--- a/app/controllers/pseudonyms_controller.rb
+++ b/app/controllers/pseudonyms_controller.rb
@ -155,16 +155,16 @@ class PseudonymsController < ApplicationController
  # @API Create a user login
  # Create a new login for an existing user in the given account.
  #
-  # @argument user[id] [String]
+  # @argument user[id] [Required, String]
  #   The ID of the user to create the login for.
  #
-  # @argument login[unique_id] [String]
+  # @argument login[unique_id] [Required, String]
  #   The unique ID for the new login.
  #
-  # @argument login[password] [Optional, String]
+  # @argument login[password] [String]
  #   The new login's password.
  #
-  # @argument login[sis_user_id] [Optional, String]
+  # @argument login[sis_user_id] [String]
  #   SIS ID for the login. To set this parameter, the caller must be able to
  #   manage SIS permissions on the account.
  def create
@ -228,14 +228,14 @@ class PseudonymsController < ApplicationController
  # @API Edit a user login
  # Update an existing login for a user in the given account.
  #
-  # @argument login[unique_id] [Optional, String]
+  # @argument login[unique_id] [String]
  #   The new unique ID for the login.
  #
-  # @argument login[password] [Optional, String]
+  # @argument login[password] [String]
  #   The new password for the login. Can only be set by an admin user if admins
  #   are allowed to change passwords for the account.
  #
-  # @argument login[sis_user_id] [Optional, String]
+  # @argument login[sis_user_id] [String]
  #   SIS ID for the login. To set this parameter, the caller must be able to
  #   manage SIS permissions on the account.
  def update