API doc standardization - part 10

groups, media_tracks, migration_issues, outcome_groups controllers

Change-Id: I06b73443d13139c9dfe84e862230dc0fef9a4f30
Reviewed-on: https://gerrit.instructure.com/23311
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Nathan Mills <nathanm@instructure.com>
Product-Review: Duane Johnson <duane@instructure.com>
QA-Review: Duane Johnson <duane@instructure.com>

app/controllers/group_memberships_controller.rb

@@ -53,9 +53,9 @@ class GroupMembershipsController < ApplicationController
   #
   # List the members of a group.
   #
-  # @argument filter_states[] [Optional] Only list memberships with the given
-  #   workflow_states. Allowed values are "accepted", "invited", and
-  #   "requested". By default it will return all memberships.
+  # @argument filter_states[] [Optional, String, "accepted"|"invited"|"requested"]
+  #   Only list memberships with the given workflow_states. By default it will
+  #   return all memberships.
   #
   # @example_request
   #     curl https://<canvas>/api/v1/groups/<group_id>/memberships \ 
@@ -85,7 +85,7 @@ class GroupMembershipsController < ApplicationController
   # group.  If the membership or join request already exists, then it is simply
   # returned
   #
-  # @argument user_id
+  # @argument user_id [String]
   #
   # @example_request
   #     curl https://<canvas>/api/v1/groups/<group_id>/memberships \ 
@@ -109,7 +109,9 @@ class GroupMembershipsController < ApplicationController
   #
   # Accept a membership request, or add/remove moderator rights.
   #
-  # @argument workflow_state Currently, the only allowed value is "accepted"
+  # @argument workflow_state [Optional, String, "accepted"]
+  #   Currently, the only allowed value is "accepted"
+  #
   # @argument moderator
   #
   # @example_request

app/controllers/groups_controller.rb

@@ -146,8 +146,8 @@ class GroupsController < ApplicationController
   #
   # Returns a list of active groups for the current user.
   #
-  # @argument context_type [Optional] only include groups that are in this type of
-  #  context. Can be 'Account' or 'Course'
+  # @argument context_type [Optional, String, "Account"|"Course"]
+  #  Only include groups that are in this type of context.
   #
   # @example_request
   #     curl https://<canvas>/api/v1/users/self/groups?context_type=Account \ 
@@ -306,15 +306,20 @@ class GroupsController < ApplicationController
   # Creates a new group. Groups created using the "/api/v1/groups/"
   # endpoint will be community groups.
   #
-  # @argument name the name of the group
-  # @argument description a description of the group
-  # @argument is_public whether the group is public (applies only to
-  #   community groups)
-  # @argument join_level parent_context_auto_join, parent_context_request,
-  #   or invitation_only
-  # @argument storage_quota_mb The allowed file storage for the group,
-  #   in megabytes. This parameter is ignored if the caller does not have
-  #   the manage_storage_quotas permission.
+  # @argument name [String]
+  #  The name of the group
+  #
+  # @argument description [String]
+  #  A description of the group
+  #
+  # @argument is_public [Boolean]
+  #   whether the group is public (applies only to community groups)
+  #
+  # @argument join_level [String, "parent_context_auto_join"|"parent_context_request"|"invitation_only"]
+  #
+  # @argument storage_quota_mb [Integer]
+  #   The allowed file storage for the group, in megabytes. This parameter is
+  #   ignored if the caller does not have the manage_storage_quotas permission.
   #
   # @example_request
   #     curl https://<canvas>/api/v1/groups \ 
@@ -376,16 +381,25 @@ class GroupsController < ApplicationController
   # {file:file_uploads.html File Upload Documentation} for details on the file
   # upload workflow.
   #
-  # @argument name
-  # @argument description
-  # @argument is_public Currently you cannot set a group back to private once
-  #   it has been made public.
-  # @argument join_level
-  # @argument avatar_id The id of the attachment previously uploaded to the
-  #   group that you would like to use as the avatar image for this group.
-  # @argument storage_quota_mb The allowed file storage for the group,
-  #   in megabytes. This parameter is ignored if the caller does not have
-  #   the manage_storage_quotas permission.
+  # @argument name [String]
+  #  The name of the group
+  #
+  # @argument description [String]
+  #  A description of the group
+  #
+  # @argument is_public [Boolean]
+  #   Whether the group is public (applies only to community groups). Currently
+  #   you cannot set a group back to private once it has been made public.
+  #
+  # @argument join_level [String, "parent_context_auto_join"|"parent_context_request"|"invitation_only"]
+  #
+  # @argument avatar_id [Integer]
+  #   The id of the attachment previously uploaded to the group that you would
+  #   like to use as the avatar image for this group.
+  #
+  # @argument storage_quota_mb [Integer]
+  #   The allowed file storage for the group, in megabytes. This parameter is
+  #   ignored if the caller does not have the manage_storage_quotas permission.
   #
   # @example_request
   #     curl https://<canvas>/api/v1/groups/<group_id> \ 
@@ -512,7 +526,8 @@ class GroupsController < ApplicationController
   # Sends an invitation to all supplied email addresses which will allow the
   # receivers to join the group.
   #
-  # @argument invitees An array of email addresses to be sent invitations
+  # @argument invitees[] [String]
+  #   An array of email addresses to be sent invitations.
   #
   # @example_request
   #     curl https://<canvas>/api/v1/groups/<group_id>/invite \ 
@@ -576,9 +591,9 @@ class GroupsController < ApplicationController
   #
   # Returns a list of users in the group.
   #
-  # @argument search_term (optional)
-  #   The partial name or full ID of the users to match and return in the results list.
-  #   Must be at least 3 characters.
+  # @argument search_term [Optional, String]
+  #   The partial name or full ID of the users to match and return in the
+  #   results list. Must be at least 3 characters.
   #
   # @example_request
   #     curl https://<canvas>/api/v1/groups/1/users \
@@ -660,7 +675,8 @@ class GroupsController < ApplicationController
   #
   # Preview html content processed for this group
   #
-  # @argument html The html content to process
+  # @argument html [String]
+  #   The html content to process
   #
   # @example_request
   #     curl https://<canvas>/api/v1/groups/<group_id>/preview_html \

app/controllers/media_tracks_controller.rb

@@ -26,9 +26,14 @@ class MediaTracksController < ApplicationController
   #
   # Create a new media track to be used as captions for different languages or deaf users. for more info, {https://developer.mozilla.org/en-US/docs/HTML/HTML_Elements/track read the MDN docs}
   #
-  # @argument kind one of: [subtitles, captions, descriptions, chapters, metadata]. default: 'subtitles'
-  # @argument locale Language code of the track being uploaded, examples: ["en", "es", "ru"]
-  # @argument content The contets of the track, in SRT or WebVTT format
+  # @argument kind [String, "subtitles"|"captions"|"descriptions"|"chapters"|"metadata"]
+  #   Default is 'subtitles'.
+  #
+  # @argument locale [String]
+  #   Language code of the track being uploaded, examples: ["en", "es", "ru"]
+  #
+  # @argument content [String]
+  #   The contets of the track, in SRT or WebVTT format
   #
   # @example_request
   #     curl https://<canvas>/media_objects/<media_object_id>/media_tracks \

app/controllers/migration_issues_controller.rb

@@ -89,7 +89,8 @@ class MigrationIssuesController < ApplicationController
   # @API Update a migration issue
   # Update the workflow_state of a migration issue
   #
-  # @argument workflow_state Set the workflow_state of the issue, only 'active' and 'resolved' accepted
+  # @argument workflow_state [String, "active"|"resolved"]
+  #   Set the workflow_state of the issue.
   #
   # @example_request
   #

app/controllers/outcome_groups_api_controller.rb

@@ -160,10 +160,17 @@ class OutcomeGroupsApiController < ApplicationController
   # the same context as this outcome group, and must not be a descendant of
   # this outcome group (i.e. no cycles allowed).
   #
-  # @argument title [Optional] The new outcome group title.
-  # @argument description [Optional] The new outcome group description.
-  # @argument vendor_guid [Optional] A custom GUID for the learning standard.
-  # @argument parent_outcome_group_id [Optional, Integer] The id of the new parent outcome group.
+  # @argument title [Optional, String]
+  #   The new outcome group title.
+  #
+  # @argument description [Optional, String]
+  #   The new outcome group description.
+  #
+  # @argument vendor_guid [Optional, String]
+  #   A custom GUID for the learning standard.
+  #
+  # @argument parent_outcome_group_id [Optional, Integer]
+  #   The id of the new parent outcome group.
   #
   # @returns OutcomeGroup
   #
@@ -330,13 +337,26 @@ class OutcomeGroupsApiController < ApplicationController
   # default of 0. If no ratings are provided, the mastery_points parameter is
   # ignored.
   #
-  # @argument outcome_id [Optional, Integer] The ID of the existing outcome to link.
-  # @argument title [Optional] The title of the new outcome. Required if outcome_id is absent.
-  # @argument description [Optional] The description of the new outcome.
-  # @argument vendor_guid [Optional] A custom GUID for the learning standard.
-  # @argument mastery_points [Optional, Integer] The mastery threshold for the embedded rubric criterion.
-  # @argument ratings[][description] [Optional] The description of a rating level for the embedded rubric criterion.
-  # @argument ratings[][points] [Optional, Integer] The points corresponding to a rating level for the embedded rubric criterion.
+  # @argument outcome_id [Optional, Integer]
+  #   The ID of the existing outcome to link.
+  #
+  # @argument title [Optional, String]
+  #   The title of the new outcome. Required if outcome_id is absent.
+  #
+  # @argument description [Optional, String]
+  #   The description of the new outcome.
+  #
+  # @argument vendor_guid [Optional, String]
+  #   A custom GUID for the learning standard.
+  #
+  # @argument mastery_points [Optional, Integer]
+  #   The mastery threshold for the embedded rubric criterion.
+  #
+  # @argument ratings[][description] [Optional, String]
+  #   The description of a rating level for the embedded rubric criterion.
+  #
+  # @argument ratings[][points] [Optional, Integer]
+  #   The points corresponding to a rating level for the embedded rubric criterion.
   #
   # @returns OutcomeLink
   #
@@ -461,9 +481,14 @@ class OutcomeGroupsApiController < ApplicationController
   # Creates a new empty subgroup under the outcome group with the given title
   # and description.
   #
-  # @argument title [Required] The title of the new outcome group.
-  # @argument description [Optional] The description of the new outcome group.
-  # @argument vendor_guid [Optional] A custom GUID for the learning standard
+  # @argument title [String]
+  #   The title of the new outcome group.
+  #
+  # @argument description [Optional, String]
+  #   The description of the new outcome group.
+  #
+  # @argument vendor_guid [Optional, String]
+  #   A custom GUID for the learning standard
   #
   # @returns OutcomeGroup
   #
@@ -515,7 +540,8 @@ class OutcomeGroupsApiController < ApplicationController
   # outcome group, or from an associated account. The source group cannot be
   # the root outcome group of its context.
   #
-  # @argument source_outcome_group_id [Required, Integer] The ID of the source outcome group.
+  # @argument source_outcome_group_id [Integer]
+  #   The ID of the source outcome group.
   #
   # @returns OutcomeGroup
   #