converting @object notation to @model part 6/11

converting for:
favorites controller
feature flags controller
files controller
folders controller
grade change audit api controller

Contributed by github.com/mcgachey

Fixes SIS-146

Currently, some API objects are documented using the @object tag, and
others are documented using @model. The @model tag is preferred because
it provides more information in the machine-readable Swagger documents
generated by the API documentation build step. For example, the @object
notation does not give a way to specify that a model property contains
an instance of another type. This complete information is necessary in
order to build an SDK generator.

This change converts the @object notations into @model, adding missing
type information and correcting inaccurate data (for example, dates were
typed as "string" in the existing JSON documentation). Embedded types are
also separated out so that their format can also be documented - this
information was previously lost.

The change also makes two minor fixes to the HTML and JSON documentation
generators. The HTML generator is fixed so that a missing documentation
string is ignored rather than being shown as an empty comment, and the
JSON generator is modified so that the Model-level documentation and
required attributes are properly provided.

Note that the JSON generated here is not fully-complient to the Swagger
format. Swagger does not support a Map structure, but the Canvas API
uses (semi-)arbitrary key/value dictionaries in a few places. In those
instances the properties are typed as "map", but this is not a part of the
Swagger spec. Any cleaner alternative approaches here would be welcome.

Change-Id: I5d90bd33f393f5b55c6a4d50b7e92c87648b9ba3
Reviewed-on: https://gerrit.instructure.com/30000
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Rob Orton <rob@instructure.com>
Product-Review: Rob Orton <rob@instructure.com>
QA-Review: Rob Orton <rob@instructure.com>