api: convert communication channels to @object/@returns

test plan:
- render the api docs
- they should use the new object/returns notation

Change-Id: Ifc2e4feca699abad8b9781c9dc81cba1808b346a
Reviewed-on: https://gerrit.instructure.com/13257
Reviewed-by: Jeremy Stanley <jeremy@instructure.com>
Tested-by: Jenkins <jenkins@instructure.com>

app/controllers/communication_channels_controller.rb

@@ -23,23 +23,47 @@
 #
 # In this API, the `:user_id` parameter can always be replaced with `self` if
 # the requesting user is asking for his/her own information.
+#
+# @object Communication Channel
+#     {
+#       // The ID of the communication channel.
+#       "id": 16,
+#
+#       // The address, or path, of the communication channel.
+#       "address": "sheldon@caltech.example.com",
+#
+#       // The type of communcation channel being described. Possible values
+#       // are: "email", "sms", "chat", "facebook" or "twitter". This field
+#       // determines the type of value seen in "address".
+#       "type": "email",
+#
+#       // The position of this communication channel relative to the user's
+#       // other channels when they are ordered.
+#       "position": 1,
+#
+#       // The ID of the user that owns this communication channel.
+#       "user_id": 1,
+#
+#       // The current state of the communication channel. Possible values are:
+#       // "unconfirmed" or "active".
+#       "workflow_state": "active"
+#     }
 class CommunicationChannelsController < ApplicationController
   before_filter :require_user, :only => [:create, :destroy]
   before_filter :reject_student_view_student
 
   include Api::V1::CommunicationChannel
 
-  # @API
-  # List the communication channels for a user.
+  # @API List user communication channels
+  #
+  # Returns a list of communication channels for the specified user, sorted by
+  # position.
   #
   # @example_request
-  #   curl https://<canvas>/api/v1/users/12345/communication_channels -H 'Authorization: Bearer <ACCESS_TOKEN>'
+  #     curl https://<canvas>/api/v1/users/12345/communication_channels \ 
+  #          -H 'Authorization: Bearer <token>'
   #
-  # @example_response
-  #   [
-  #     { "id": 1, "address": "bieberfever@example.com", "type": "email", "position": 1, "user_id": 12345 },
-  #     { "id": 2, "address": "8018675309", "type": "sms", "position": 2, "user_id": 12345 }
-  #   ]
+  # @returns [Communication Channel]
   def index
     @user = api_find(User, params[:user_id])
     return unless authorized_action(@user, @current_user, :read)
@@ -52,31 +76,21 @@ class CommunicationChannelsController < ApplicationController
     render :json => channels
   end
 
-  # @API Create a new communication channel.
+  # @API Create a communication channel
+  #
+  # Creates a new communication channel for the specified user.
   #
   # @argument communication_channel[address] An email address or SMS number.
   # @argument communication_channel[type] [email|sms] The type of communication channel.
-  # @argument skip_confirmation [Optional] Only valid for site admins making requests; If '1', the
-  # channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must
-  # respond to a confirmation message to confirm the channel.
+  # @argument skip_confirmation [Optional] Only valid for site admins making requests; If '1', the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.
   #
   # @example_request
+  #     curl https://<canvas>/api/v1/users/1/communication_channels \ 
+  #          -H 'Authorization: Bearer <token>' \ 
+  #          -d 'communication_channel[address]=new@example.com' \ 
+  #          -d 'communication_channel[type]=email' \ 
   #
-  #   curl https://<canvas>/api/v1/users/1/communication_channels \ 
-  #     -H 'Authorization: Bearer <ACCESS_TOKEN>' \ 
-  #     -d 'communication_channel[address]=new@example.com' \ 
-  #     -d 'communication_channel[type]=email' \ 
-  #
-  # @example_response
-  #
-  #   {
-  #     "id": 2,
-  #     "address": "new@example.com",
-  #     "type": "email",
-  #     "workflow_state": "unconfirmed",
-  #     "user_id": 1,
-  #     "position": 2
-  #   }
+  # @returns Communication Channel
   def create
     @user = api_request? ? api_find(User, params[:user_id]) : @current_user
 
@@ -310,23 +324,16 @@ class CommunicationChannelsController < ApplicationController
     render :json => {:re_sent => true}
   end
 
-  # @API Delete a communication channel.
+  # @API Delete a communication channel
+  #
   # Delete an existing communication channel.
   #
   # @example_request
-  #   curl https://<canvas>/api/v1/users/5/communication_channels/3
-  #     -H 'Authorization: Bearer <ACCESS_TOKEN>
-  #     -X DELETE
+  #     curl https://<canvas>/api/v1/users/5/communication_channels/3
+  #          -H 'Authorization: Bearer <token>
+  #          -X DELETE
   #
-  # @example_response
-  #   {
-  #     "id": 3,
-  #     "address": "new@example.com",
-  #     "type": "email",
-  #     "workflow_state": "deleted",
-  #     "user_id": 5,
-  #     "position": 2
-  #   }
+  # @returns Communication Channel
   def destroy
     @user = api_request? ? api_find(User, params[:user_id]) : @current_user
     @cc   = @user.communication_channels.find(params[:id]) if params[:id]

app/controllers/courses_controller.rb

@@ -158,6 +158,7 @@ class CoursesController < ApplicationController
   def create
     @account = params[:account_id] ? Account.find(params[:account_id]) : @domain_root_account.manually_created_courses_account
     if authorized_action(@account, @current_user, [:manage_courses, :create_courses])
+      params[:course] ||= {}
       if (sub_account_id = params[:course].delete(:account_id)) && sub_account_id.to_i != @account.id
         @sub_account = @account.find_child(sub_account_id) || raise(ActiveRecord::RecordNotFound)
       end

lib/api/v1/communication_channel.rb

@@ -20,8 +20,14 @@ module Api::V1::CommunicationChannel
   include Api::V1::Json
 
   # Internal: The attributes returned by communication_channel_json.
+  #
+  # Uses the method "path_description" instead of the field "path" because
+  # when path_type is facebook or twitter, it goes and fetches tha user's account
+  # name with a fallback display value.
   JSON_OPTS = {
-    :only => %w{ id path path_type position workflow_state user_id } }
+    :only => %w{ id path_type position workflow_state user_id },
+    :methods => %w{ path_description }
+  }
 
   # Public: Given a communication channel, return it in an API-friendly format.
   #
@@ -38,11 +44,8 @@ module Api::V1::CommunicationChannel
   #   :workflow_state
   def communication_channel_json(channel, current_user, session)
     api_json(channel, current_user, session, JSON_OPTS).tap do |json|
-      # Replace "path" with "path_description" and rename as "address". Reason for path_description is for when the
-      # path_type is facebook or twitter, it goes and fetches tha user's account name with a fallback display value.
-      json.delete(:path)
-      json[:address] = channel.path_description
       # Rename attributes for mass-consumption
+      json[:address] = json.delete(:path_description)
       json[:type]    = json.delete(:path_type)
     end
   end