update API doc required params - 8

- Notification preferences - Outcome groups - Outcome results - Outcomes - Pages Test plan: - rake doc:api - Verify the above doc pages for parameter accuracy Refs SIS-403 Change-Id: I98fd1370902bb7570d75713b569a3b0779bf408a Reviewed-on: https://gerrit.instructure.com/39311 Tested-by: Jenkins <jenkins@instructure.com> Reviewed-by: Duane Johnson <duane@instructure.com> Product-Review: Duane Johnson <duane@instructure.com> QA-Review: Jeremy Putnam <jeremyp@instructure.com>
2014-08-14 11:26:45 -06:00 · 2014-08-14 11:26:45 -06:00 · 15b49f203d
parent e7a4faf0d3
commit 15b49f203d
5 changed files with 50 additions and 50 deletions
--- a/app/controllers/notification_preferences_controller.rb
+++ b/app/controllers/notification_preferences_controller.rb
@ -77,7 +77,7 @@ class NotificationPreferencesController < ApplicationController

  # @API Update a preference
  # Change the preference for a single notification for a single communication channel
-  # @argument notification_preferences[frequency] The desired frequency for this notification
+  # @argument notification_preferences[frequency] [Required] The desired frequency for this notification
  def update
    return render_unauthorized_action unless @user == @current_user
    # support both JSON API style (notification preferences is an array) and Canvas API style (it's a hash)
@ -87,7 +87,7 @@ class NotificationPreferencesController < ApplicationController

  # @API Update multiple preferences
  # Change the preferences for multiple notifications for a single communication channel at once
-  # @argument notification_preferences[<X>][frequency] The desired frequency for <X> notification
+  # @argument notification_preferences[<X>][frequency] [Required] The desired frequency for <X> notification
  def update_all
    return render_unauthorized_action unless @user == @current_user
    policies = []
--- a/app/controllers/outcome_groups_api_controller.rb
+++ b/app/controllers/outcome_groups_api_controller.rb
@ -201,16 +201,16 @@ 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, String]
+  # @argument title [String]
  #   The new outcome group title.
  #
-  # @argument description [Optional, String]
+  # @argument description [String]
  #   The new outcome group description.
  #
-  # @argument vendor_guid [Optional, String]
+  # @argument vendor_guid [String]
  #   A custom GUID for the learning standard.
  #
-  # @argument parent_outcome_group_id [Optional, Integer]
+  # @argument parent_outcome_group_id [Integer]
  #   The id of the new parent outcome group.
  #
  # @returns OutcomeGroup
@ -378,29 +378,29 @@ class OutcomeGroupsApiController < ApplicationController
  # default of 0. If no ratings are provided, the mastery_points parameter is
  # ignored.
  #
-  # @argument outcome_id [Optional, Integer]
+  # @argument outcome_id [Integer]
  #   The ID of the existing outcome to link.
  #
-  # @argument title [Optional, String]
+  # @argument title [String]
  #   The title of the new outcome. Required if outcome_id is absent.
  #
-  # @argument display_name [Optional, String]
+  # @argument display_name [String]
  #   A friendly name shown in reports for outcomes with cryptic titles,
  #   such as common core standards names.
  #
-  # @argument description [Optional, String]
+  # @argument description [String]
  #   The description of the new outcome.
  #
-  # @argument vendor_guid [Optional, String]
+  # @argument vendor_guid [String]
  #   A custom GUID for the learning standard.
  #
-  # @argument mastery_points [Optional, Integer]
+  # @argument mastery_points [Integer]
  #   The mastery threshold for the embedded rubric criterion.
  #
-  # @argument ratings[][description] [Optional, String]
+  # @argument ratings[][description] [String]
  #   The description of a rating level for the embedded rubric criterion.
  #
-  # @argument ratings[][points] [Optional, Integer]
+  # @argument ratings[][points] [Integer]
  #   The points corresponding to a rating level for the embedded rubric criterion.
  #
  # @returns OutcomeLink
@ -528,13 +528,13 @@ class OutcomeGroupsApiController < ApplicationController
  # Creates a new empty subgroup under the outcome group with the given title
  # and description.
  #
-  # @argument title [String]
+  # @argument title [Required, String]
  #   The title of the new outcome group.
  #
-  # @argument description [Optional, String]
+  # @argument description [String]
  #   The description of the new outcome group.
  #
-  # @argument vendor_guid [Optional, String]
+  # @argument vendor_guid [String]
  #   A custom GUID for the learning standard
  #
  # @returns OutcomeGroup
@ -587,7 +587,7 @@ 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 [Integer]
+  # @argument source_outcome_group_id [Required, Integer]
  #   The ID of the source outcome group.
  #
  # @returns OutcomeGroup
--- a/app/controllers/outcome_results_controller.rb
+++ b/app/controllers/outcome_results_controller.rb
@ -191,17 +191,17 @@ class OutcomeResultsController < ApplicationController
  #
  # Gets the outcome results for users and outcomes in the specified context.
  #
-  # @argument user_ids[] [Optional, Integer]
+  # @argument user_ids[] [Integer]
  #   If specified, only the users whose ids are given will be included in the
  #   results. it is an error to specify an id for a user who is not a student in
  #   the context
  #
-  # @argument outcome_ids[] [Optional, Integer]
+  # @argument outcome_ids[] [Integer]
  #   If specified, only the outcomes whose ids are given will be included in the
  #   results. it is an error to specify an id for an outcome which is not linked
  #   to the context.
  #
-  # @argument include[] [Optional, String, "alignments"|"outcomes"|"outcomes.alignments"|"outcome_groups"|"outcome_links"|"outcome_paths"|"users"]
+  # @argument include[] [String, "alignments"|"outcomes"|"outcomes.alignments"|"outcome_groups"|"outcome_links"|"outcome_paths"|"users"]
  #   Specify additional collections to be side loaded with the result.
  #   "alignments" includes only the alignments referenced by the returned
  #   results.
@ -226,22 +226,22 @@ class OutcomeResultsController < ApplicationController
  # Gets the outcome rollups for the users and outcomes in the specified
  # context.
  #
-  # @argument aggregate [Optional, String, "course"]
+  # @argument aggregate [String, "course"]
  #   If specified, instead of returning one rollup for each user, all the user
  #   rollups will be combined into one rollup for the course that will contain
  #   the average rollup score for each outcome.
  #
-  # @argument user_ids[] [Optional, Integer]
+  # @argument user_ids[] [Integer]
  #   If specified, only the users whose ids are given will be included in the
  #   results or used in an aggregate result. it is an error to specify an id
  #   for a user who is not a student in the context
  #
-  # @argument outcome_ids[] [Optional, Integer]
+  # @argument outcome_ids[] [Integer]
  #   If specified, only the outcomes whose ids are given will be included in the
  #   results. it is an error to specify an id for an outcome which is not linked
  #   to the context.
  #
-  # @argument include[] [Optional, String, "courses"|"outcomes"|"outcomes.alignments"|"outcome_groups"|"outcome_links"|"outcome_paths"|"users"]
+  # @argument include[] [String, "courses"|"outcomes"|"outcomes.alignments"|"outcome_groups"|"outcome_links"|"outcome_paths"|"users"]
  #   Specify additional collections to be side loaded with the result.
  #
  # @example_response
--- a/app/controllers/outcomes_api_controller.rb
+++ b/app/controllers/outcomes_api_controller.rb
@ -120,26 +120,26 @@ class OutcomesApiController < ApplicationController
  # description". Any new ratings lacking a point value are given a default of
  # 0.
  #
-  # @argument title [Optional, String]
+  # @argument title [String]
  #   The new outcome title.
  #
-  # @argument display_name [Optional, String]
+  # @argument display_name [String]
  #   A friendly name shown in reports for outcomes with cryptic titles,
  #   such as common core standards names.
  #
-  # @argument description [Optional, String]
+  # @argument description [String]
  #   The new outcome description.
  #
-  # @argument vendor_guid [Optional, String]
+  # @argument vendor_guid [String]
  #   A custom GUID for the learning standard.
  #
-  # @argument mastery_points [Optional, Integer]
+  # @argument mastery_points [Integer]
  #   The new mastery threshold for the embedded rubric criterion.
  #
-  # @argument ratings[][description] [Optional, String]
+  # @argument ratings[][description] [String]
  #   The description of a new rating level for the embedded rubric criterion.
  #
-  # @argument ratings[][points] [Optional, Integer]
+  # @argument ratings[][points] [Integer]
  #   The points corresponding to a new rating level for the embedded rubric
  #   criterion.
  #
--- a/app/controllers/wiki_pages_api_controller.rb
+++ b/app/controllers/wiki_pages_api_controller.rb
@ -159,21 +159,21 @@ class WikiPagesApiController < ApplicationController
  #
  # Update the title or contents of the front page
  #
-  # @argument wiki_page[title] [Optional, String]
+  # @argument wiki_page[title] [String]
  #   The title for the new page. NOTE: changing a page's title will change its
  #   url. The updated url will be returned in the result.
  #
  # @argument wiki_page[body] [String]
  #   The content for the new page.
  #
-  # @argument wiki_page[hide_from_students] [Optional, Boolean]
+  # @argument wiki_page[hide_from_students] [Boolean]
  #   Whether the page should be hidden from students.
  #
  #   *Note:* when draft state is enabled, attempts to set +hide_from_students+
  #   will be ignored and the value returned will always be the inverse of the
  #   +published+ value.
  #
-  # @argument wiki_page[editing_roles] [Optional, String, "teachers"|"students"|"members"|"public"]
+  # @argument wiki_page[editing_roles] [String, "teachers"|"students"|"members"|"public"]
  #   Which user roles are allowed to edit this page. Any combination
  #   of these roles is allowed (separated by commas).
  #
@ -182,10 +182,10 @@ class WikiPagesApiController < ApplicationController
  #   "members":: For group wikis, allows editing by members of the group.
  #   "public":: Allows editing by any user.
  #
-  # @argument wiki_page[notify_of_update] [Optional, Boolean]
+  # @argument wiki_page[notify_of_update] [Boolean]
  #   Whether participants should be notified when this page changes.
  #
-  # @argument wiki_page[published] [Optional, Boolean]
+  # @argument wiki_page[published] [Boolean]
  #   Whether the page is published (true) or draft state (false).
  #
  #   *Note:* when draft state is disabled, attempts to set +published+
@ -206,16 +206,16 @@ class WikiPagesApiController < ApplicationController
  #
  # List the wiki pages associated with a course or group
  #
-  # @argument sort [Optional, String, "title"|"created_at"|"updated_at"]
+  # @argument sort [String, "title"|"created_at"|"updated_at"]
  #   Sort results by this field.
  #
-  # @argument order [Optional, String, "asc"|"desc"]
+  # @argument order [String, "asc"|"desc"]
  #   The sorting order. Defaults to 'asc'.
  #
-  # @argument search_term [Optional, String]
+  # @argument search_term [String]
  #   The partial title of the pages to match and return.
  #
-  # @argument published [Optional, Boolean]
+  # @argument published [Boolean]
  #   If true, include only published paqes. If false, exclude published
  #   pages. If not present, do not filter on published status.
  #
@ -262,7 +262,7 @@ class WikiPagesApiController < ApplicationController
  #
  # Create a new wiki page
  #
-  # @argument wiki_page[title] [String]
+  # @argument wiki_page[title] [Required, String]
  #   The title for the new page.
  #
  # @argument wiki_page[body] [String]
@ -275,7 +275,7 @@ class WikiPagesApiController < ApplicationController
  #   will be ignored and the value returned will always be the inverse of the
  #   +published+ value.
  #
-  # @argument wiki_page[editing_roles] [Optional, String, "teachers"|"students"|"members"|"public"]
+  # @argument wiki_page[editing_roles] [String, "teachers"|"students"|"members"|"public"]
  #   Which user roles are allowed to edit this page. Any combination
  #   of these roles is allowed (separated by commas).
  #
@ -287,14 +287,14 @@ class WikiPagesApiController < ApplicationController
  # @argument wiki_page[notify_of_update] [Boolean]
  #   Whether participants should be notified when this page changes.
  #
-  # @argument wiki_page[published] [Optional, Boolean]
+  # @argument wiki_page[published] [Boolean]
  #   Whether the page is published (true) or draft state (false).
  #
  #   *Note:* when draft state is disabled, attempts to set +published+
  #   will be ignored and the value returned will always be the inverse of the
  #   +hide_from_students+ value.
  #
-  # @argument wiki_page[front_page] [Optional, Boolean]
+  # @argument wiki_page[front_page] [Boolean]
  #   Set an unhidden page as the front page (if true)
  #
  # @example_request
@ -356,7 +356,7 @@ class WikiPagesApiController < ApplicationController
  #   will be ignored and the value returned will always be the inverse of the
  #   +published+ value.
  #
-  # @argument wiki_page[editing_roles] [Optional, String, "teachers"|"students"|"members"|"public"]
+  # @argument wiki_page[editing_roles] [String, "teachers"|"students"|"members"|"public"]
  #   Which user roles are allowed to edit this page. Any combination
  #   of these roles is allowed (separated by commas).
  #
@ -368,14 +368,14 @@ class WikiPagesApiController < ApplicationController
  # @argument wiki_page[notify_of_update] [Boolean]
  #   Whether participants should be notified when this page changes.
  #
-  # @argument wiki_page[published] [Optional, Boolean]
+  # @argument wiki_page[published] [Boolean]
  #   Whether the page is published (true) or draft state (false).
  #
  #   *Note:* when draft state is disabled, attempts to set +published+
  #   will be ignored and the value returned will always be the inverse of the
  #   +hide_from_students+ value.
  #
-  # @argument wiki_page[front_page] [Optional, Boolean]
+  # @argument wiki_page[front_page] [Boolean]
  #   Set an unhidden page as the front page (if true)
  #
  # @example_request
@ -450,7 +450,7 @@ class WikiPagesApiController < ApplicationController
  # Retrieve the metadata and optionally content of a revision of the page.
  # Note that retrieving historic versions of pages requires edit rights.
  #
-  # @argument summary [Optional, Boolean]
+  # @argument summary [Boolean]
  #   If set, exclude page content from results
  #
  # @example_request
@ -484,7 +484,7 @@ class WikiPagesApiController < ApplicationController
  #
  # Revert a page to a prior revision.
  #
-  # @argument revision_id [Integer]
+  # @argument revision_id [Required, Integer]
  #   The revision to revert to (use the
  #   {api:WikiPagesApiController#revisions List Revisions API} to see
  #   available revisions)