From 88f69ccb51a89cd1ab74e8a7e6ae30a080168729 Mon Sep 17 00:00:00 2001 From: Duane Johnson Date: Tue, 13 Aug 2013 16:54:33 -0600 Subject: [PATCH] API doc standardization - part 2 admin, appointment_group controllers Change-Id: Ic6594692b1547cd4e0301345ee46f0c84b60d7c1 Reviewed-on: https://gerrit.instructure.com/23294 Tested-by: Jenkins Reviewed-by: Brian Palmer Product-Review: Duane Johnson QA-Review: Duane Johnson --- app/controllers/admins_controller.rb | 14 +- .../appointment_groups_controller.rb | 160 +++++++++++++----- 2 files changed, 130 insertions(+), 44 deletions(-) diff --git a/app/controllers/admins_controller.rb b/app/controllers/admins_controller.rb index 911d674f2f0..9b92c86c1e6 100644 --- a/app/controllers/admins_controller.rb +++ b/app/controllers/admins_controller.rb @@ -44,11 +44,15 @@ class AdminsController < ApplicationController # # Flag an existing user as an admin within the account. # - # @argument user_id The id of the user to promote. + # @argument user_id [String] + # The id of the user to promote. # - # @argument role [Optional] The user's admin relationship with the account will be created with the given role. Defaults to 'AccountAdmin'. + # @argument role [Optional, String] + # The user's admin relationship with the account will be created with the + # given role. Defaults to 'AccountAdmin'. # - # @argument send_confirmation [Optional] [0|1] Send a notification email to the new admin if set to '1'; send no email if set to '0'. Default is '1'. + # @argument send_confirmation [Optional, Boolean] Send a notification email to + # the new admin if true. Default is true. # # @returns Admin def create @@ -63,7 +67,9 @@ class AdminsController < ApplicationController # # Remove the rights associated with an account admin role from a user. # - # @argument role [Optional] Account role to remove from the user. Defaults to 'AccountAdmin'. Any other account role must be specified explicitly. + # @argument role [Optional, String] + # Account role to remove from the user. Defaults to 'AccountAdmin'. Any + # other account role must be specified explicitly. # # @returns Admin def destroy diff --git a/app/controllers/appointment_groups_controller.rb b/app/controllers/appointment_groups_controller.rb index d7c8a1fda49..6b2301ec455 100644 --- a/app/controllers/appointment_groups_controller.rb +++ b/app/controllers/appointment_groups_controller.rb @@ -139,16 +139,23 @@ class AppointmentGroupsController < ApplicationController # Retrieve the list of appointment groups that can be reserved or managed by # the current user. # - # @argument scope [Optional, "reservable"|"manageable"] Defaults to "reservable" - # @argument context_codes[] [Optional] Array of context codes used to limit returned results. - # @argument include_past_appointments [Optional] Boolean, defaults to false. - # If true, includes past appointment groups - # @argument include[] [Optional] Array of additional information to include. - # Allowable values include "appointments" (i.e. calendar event time slots - # for this appointment group), "child_events" (i.e. reservations of those - # time slots), "participant_count" (i.e. number of reservations), and - # "reserved_times" (i.e. the event id, start time and end time of - # reservations the current user has made) + # @argument scope [Optional, String, "reservable"|"manageable"] + # Defaults to "reservable" + # + # @argument context_codes[] [Optional, String] + # Array of context codes used to limit returned results. + # + # @argument include_past_appointments [Optional, Boolean] + # Defaults to false. If true, includes past appointment groups + # + # @argument include[] [Optional, "appointments"|"child_events"|"participant_count"|"reserved_times"] + # Array of additional information to include. + # + # "appointments":: calendar event time slots for this appointment group + # "child_events":: reservations of those time slots + # "participant_count":: number of reservations + # "reserved_times":: the event id, start time and end time of reservations + # the current user has made) def index unless request.format == :json anchor = calendar_fragment :view_name => :scheduler @@ -194,18 +201,54 @@ class AppointmentGroupsController < ApplicationController # specified, the response will return a new_appointments array (same format # as appointments array, see "List appointment groups" action) # - # @argument appointment_group[context_codes][] [Required] Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group. - # @argument appointment_group[sub_context_codes][] [Optional] Array of sub context codes (course sections or a single group category) this group should be linked to. Used to limit the appointment group to particular sections. If a group category is specified, students will sign up in groups and the participant_type will be "Group" instead of "User". - # @argument appointment_group[title] [Optional] Short title for the appointment group. - # @argument appointment_group[description] [Optional] Longer text description of the appointment group. - # @argument appointment_group[location_name] [Optional] Location name of the appointment group. - # @argument appointment_group[location_address] [Optional] Location address. - # @argument appointment_group[publish] [Optional] Boolean, default false. Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. - # @argument appointment_group[participants_per_appointment] [Optional] Maximum number of participants that may register for each time slot. Defaults to null (no limit). - # @argument appointment_group[min_appointments_per_participant] [Optional] Minimum number of time slots a user must register for. If not set, users do not need to sign up for any time slots. - # @argument appointment_group[max_appointments_per_participant] [Optional] Maximum number of time slots a user may register for. - # @argument appointment_group[new_appointments][X][] [Optional] Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request. - # @argument appointment_group[participant_visibility] [Optional, "private"|"protected"] "private" means participants cannot see who has signed up for a particular time slot, "protected" means that they can. Defaults to "private". + # @argument appointment_group[context_codes][] [String] + # Array of context codes (courses, e.g. course_1) this group should be + # linked to (1 or more). Users in the course(s) with appropriate permissions + # will be able to sign up for this appointment group. + # + # @argument appointment_group[sub_context_codes][] [Optional, String] + # Array of sub context codes (course sections or a single group category) + # this group should be linked to. Used to limit the appointment group to + # particular sections. If a group category is specified, students will sign + # up in groups and the participant_type will be "Group" instead of "User". + # + # @argument appointment_group[title] [Optional, String] + # Short title for the appointment group. + # + # @argument appointment_group[description] [Optional, String] + # Longer text description of the appointment group. + # + # @argument appointment_group[location_name] [Optional, String] + # Location name of the appointment group. + # + # @argument appointment_group[location_address] [Optional, String] + # Location address. + # + # @argument appointment_group[publish] [Optional, Boolean] + # Indicates whether this appointment group should be published (i.e. made + # available for signup). Once published, an appointment group cannot be + # unpublished. Defaults to false. + # + # @argument appointment_group[participants_per_appointment] [Optional, Integer] + # Maximum number of participants that may register for each time slot. + # Defaults to null (no limit). + # + # @argument appointment_group[min_appointments_per_participant] [Optional, Integer] + # Minimum number of time slots a user must register for. If not set, users + # do not need to sign up for any time slots. + # + # @argument appointment_group[max_appointments_per_participant] [Optional, Integer] + # Maximum number of time slots a user may register for. + # + # @argument appointment_group[new_appointments][X][] [Optional] + # Nested array of start time/end time pairs indicating time slots for this + # appointment group. Refer to the example request. + # + # @argument appointment_group[participant_visibility] [Optional, "private"|"protected"] + # "private":: participants cannot see who has signed up for a particular + # time slot + # "protected":: participants can see who has signed up. Defaults to + # "private". # # @example_request # @@ -244,10 +287,12 @@ class AppointmentGroupsController < ApplicationController # # Returns information for a single appointment group # - # @argument include[] [Optional] Array of additional information to include. - # Allowable values include "child_events" (i.e. reservations of time slots - # time slots). "appointments" will always be returned (see include[] - # argument of "List appointment groups" action). + # @argument include[] [Optional, "child_events"|"appointments"] + # Array of additional information to include. Ssee include[] argument of + # "List appointment groups" action. + # + # "child_events":: reservations of time slots time slots + # "appointments":: will always be returned def show if authorized_action(@group, @current_user, :read) unless request.format == :json @@ -265,18 +310,53 @@ class AppointmentGroupsController < ApplicationController # the response will return a new_appointments array (same format as # appointments array, see "List appointment groups" action). # - # @argument appointment_group[context_codes][] [Optional] Array of context codes to add to this appointment group (existing ones cannot be removed). - # @argument appointment_group[sub_context_codes][] [Optional] Array of sub context codes to add to this appointment group (existing ones cannot be removed). - # @argument appointment_group[title] [Optional] Short title for the appointment group. - # @argument appointment_group[description] [Optional] Longer text description of the appointment group. - # @argument appointment_group[location_name] [Optional] Location name of the appointment group. - # @argument appointment_group[location_address] [Optional] Location address. - # @argument appointment_group[publish] [Optional] Boolean, default false. Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. - # @argument appointment_group[participants_per_appointment] [Optional] Maximum number of participants that may register for each time slot. Defaults to null (no limit). Changes will not affect existing reservations. - # @argument appointment_group[min_appointments_per_participant] [Optional] Minimum number of time slots a user must register for. If not set, users do not need to sign up for any time slots. Changes will not affect existing reservations. - # @argument appointment_group[max_appointments_per_participant] [Optional] Maximum number of time slots a user may register for. Changes will not affect existing reservations. - # @argument appointment_group[new_appointments][X][] [Optional] Nested array of new start time/end time pairs indicating time slots for this appointment group. Refer to the example request. To remove existing time slots or reservations, use the Calendar Event API. - # @argument appointment_group[participant_visibility] [Optional, "private"|"protected"] "private" means participants cannot see who has signed up for a particular time slot, "protected" means that they can. + # @argument appointment_group[context_codes][] [String] + # Array of context codes (courses, e.g. course_1) this group should be + # linked to (1 or more). Users in the course(s) with appropriate permissions + # will be able to sign up for this appointment group. + # + # @argument appointment_group[sub_context_codes][] [Optional, String] + # Array of sub context codes (course sections or a single group category) + # this group should be linked to. Used to limit the appointment group to + # particular sections. If a group category is specified, students will sign + # up in groups and the participant_type will be "Group" instead of "User". + # + # @argument appointment_group[title] [Optional, String] + # Short title for the appointment group. + # + # @argument appointment_group[description] [Optional, String] + # Longer text description of the appointment group. + # + # @argument appointment_group[location_name] [Optional, String] + # Location name of the appointment group. + # + # @argument appointment_group[location_address] [Optional, String] + # Location address. + # + # @argument appointment_group[publish] [Optional, Boolean] + # Indicates whether this appointment group should be published (i.e. made + # available for signup). Once published, an appointment group cannot be + # unpublished. Defaults to false. + # + # @argument appointment_group[participants_per_appointment] [Optional, Integer] + # Maximum number of participants that may register for each time slot. + # Defaults to null (no limit). + # + # @argument appointment_group[min_appointments_per_participant] [Optional, Integer] + # Minimum number of time slots a user must register for. If not set, users + # do not need to sign up for any time slots. + # + # @argument appointment_group[max_appointments_per_participant] [Optional, Integer] + # Maximum number of time slots a user may register for. + # + # @argument appointment_group[new_appointments][X][] [Optional] + # Nested array of start time/end time pairs indicating time slots for this + # appointment group. Refer to the example request. + # + # @argument appointment_group[participant_visibility] [Optional, "private"|"protected"] + # "private":: participants cannot see who has signed up for a particular + # time slot + # "protected":: participants can see who has signed up. Defaults to "private". # # @example_request # @@ -303,8 +383,8 @@ class AppointmentGroupsController < ApplicationController # Delete an appointment group (and associated time slots and reservations) # and return the deleted group # - # @argument cancel_reason [Optional] Reason for deleting/canceling the - # appointment group. + # @argument cancel_reason [Optional, String] + # Reason for deleting/canceling the appointment group. # # @example_request #