API doc update for a group assignment override

The documentation regarding creating an assignment override with
`group_id` is made more clear and the prerequisites are better stated.

The group assignments feature and the dependency between
`group_category_id` and `group_id` in the stages of assignment creation
and assignment override creation are explained by a diagram sitting in an
appendix entry at the bottom of the Assignments API documentation page,
Appendix: Group assignments.

The diagram image in the appendix is exported out of the raw .xmind file
in doc/diagrams. You can edit that diagram using the XMind program
(http://www.xmind.net/), it's free to use and cross-platform (JAVA).

---

Testing:

  1. generate the API docs: `bundle exec rake doc:api`
  2. navigate to the Assignments API page
     (link: public/doc/api/assignments.html)
  3. take a look at the "Create an assignment override"
     section
  4. also take a look at the bottom of the page

fixes #CNVS-1204

Change-Id: I07660a7e8a58aba2e307849a79557067a7ea77fb
Reviewed-on: https://gerrit.instructure.com/17454
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Simon Williams <simon@instructure.com>
QA-Review: Amber Taniuchi <amber@instructure.com>

app/controllers/assignment_overrides_controller.rb

@@ -38,7 +38,7 @@
 #       student_ids: [1, 2, 3],
 #
 #       // the ID of the override's target group (present if the override
-#       // targets a group)
+#       // targets a group and the assignment is a group assignment)
 #       group_id: 2,
 #
 #       // the ID of the overrides's target section (present if the override
@@ -138,9 +138,14 @@ class AssignmentOverridesController < ApplicationController
   #   instead).
   #
   # @argument assignment_override[group_id] [Optional, Integer] The ID of the
-  #   override's target group. If present, the assignment must be a group
-  #   assignment and the ID must identify an active group in the assignment's
-  #   group category not already targetted by a different override.
+  #   override's target group. If present, the following conditions must be met
+  #   for the override to be successful:
+  #
+  #   1. the assignment MUST be a group assignment (a group_category_id is assigned to it)
+  #   2. the ID must identify an active group in the group set the assignment is in
+  #   3. the ID must not be targetted by a different override
+  #
+  #   See {Appendix: Group assignments} for more info.
   #
   # @argument assignment_override[course_section_id] [Optional, Integer] The ID
   #   of the override's target section. If present, must identify an active
@@ -263,7 +268,6 @@ class AssignmentOverridesController < ApplicationController
   #   curl 'http://<canvas>/api/v1/courses/1/assignments/2/overrides/3.json' \ 
   #        -X DELETE \ 
   #        -H "Authorization: Bearer <token>"
-  #
   def destroy
     if @override.destroy
       render :json => assignment_override_json(@override)
@@ -306,4 +310,12 @@ class AssignmentOverridesController < ApplicationController
   def bad_request(errors)
     render :json => errors.to_json, :status => :bad_request
   end
+
+  # @!appendix Group assignments
+  #
+  #  {include:file:doc/examples/group_assignment.md}
+  #
+  #  @see api:AssignmentOverridesController#create Creating an assignment override
+  #  @see api:AssignmentsApiController#create Creating an assignment
+  #  @see api:Assignments:Assignment
 end

doc/examples/group_assignment.md

@@ -0,0 +1,21 @@
+The following diagram provides an example to describe the structure
+of group assignments. It also shows the correspondence between the
+fields of an assignment override API request and the resources they
+map to.
+
+![Group assignments structure example](./images/group_assignment.png)
+  
+The components in <span style="background: #FFDD00;">yellow</span>
+are *group sets*. When creating or updating an assignment override,
+you will refer to the group set by the `group_category_id` field.
+
+The components in <span style="background: #C1E200;">green</span>
+are *groups*. An assignment can become a group assignment iff it
+has a `group_category_id` that maps to an active group set, as well
+as a `group_id` that maps to an active, valid group. In the API,
+you will be specifying the group by the `group_id` field of the
+`assignment_override` construct.
+
+**Important**: an assignment must be assigned to a group set
+(the `group_category_id` field) on **creation** for an override
+with a `group_id` to be effective.