Fixes to JSDoc for API docs

lib/models/access-context.js

@@ -194,8 +194,8 @@ Principal.SCOPE = 'SCOPE';
 
 /**
  * Compare if two principals are equal
- * @param p The other principal
+ * Returns true if argument principal is equal to this principal.
- * @returns {boolean}
+ * @param {Object} principal The other principal
  */
 Principal.prototype.equals = function (p) {
   if (p instanceof Principal) {
@@ -205,11 +205,11 @@ Principal.prototype.equals = function (p) {
 };
 
 /**
- * A request to access protected resources
+ * A request to access protected resources.
  * @param {String} model The model name
  * @param {String} property
  * @param {String} accessType The access type
- * @param {String} permission The permission
+ * @param {String} permission The requested permission
  * @returns {AccessRequest}
  * @class
  */

lib/models/application.js

@@ -90,7 +90,7 @@ var ApplicationSchema = {
   modified: {type: Date, default: Date}
 };
 
-/**
+/*!
  * Application management functions
  */
 
@@ -189,8 +189,7 @@ Application.resetKeys = function (appId, cb) {
 /**
  * Authenticate the application id and key.
  * 
- * `matched` will be one of
+ * `matched` parameter is one of:
- * 
  * - clientKey
  * - javaScriptKey
  * - restApiKey
@@ -201,7 +200,7 @@ Application.resetKeys = function (appId, cb) {
  * @param {String} key
  * @callback {Function} callback
  * @param {Error} err
- * @param {String} matched - The matching key
+ * @param {String} matched The matching key
  */
 Application.authenticate = function (appId, key, cb) {
   this.findById(appId, function (err, app) {