diff --git a/common/models/role.js b/common/models/role.js
index 2c005cde..443ced81 100644
--- a/common/models/role.js
+++ b/common/models/role.js
@@ -9,8 +9,9 @@ var RoleMapping = loopback.RoleMapping;
 assert(RoleMapping, 'RoleMapping model must be defined before Role model');
 
 /**
- * The Role Model
+ * The Role model
  * @class Role
+ * @header Role object
  */
 module.exports = function(Role) {
 
@@ -113,7 +114,7 @@ module.exports = function(Role) {
   }
 
   /*!
-   * Check if two user ids matches
+   * Check if two user IDs matches
    * @param {*} id1
    * @param {*} id2
    * @returns {boolean}
@@ -201,11 +202,12 @@ module.exports = function(Role) {
   });
 
   /**
-   * Check if the user id is authenticated
-   * @param {Object} context The security context
-   * @callback {Function} callback
-   * @param {Error} err
-   * @param {Boolean} isAuthenticated
+   * Check if the user ID is authenticated
+   * @param {Object} context The security context.
+   *
+   * @callback {Function} callback Callback function.
+   * @param {Error} err Error object.
+   * @param {Boolean} isAuthenticated True if the user is authenticated.
    */
   Role.isAuthenticated = function isAuthenticated(context, callback) {
     process.nextTick(function() {
@@ -226,13 +228,14 @@ module.exports = function(Role) {
   });
 
   /**
-   * Check if a given principal is in the role
+   * Check if a given principal is in the specified role.
    *
-   * @param {String} role The role name
-   * @param {Object} context The context object
-   * @callback {Function} callback
-   * @param {Error} err
-   * @param {Boolean} isInRole
+   * @param {String} role The role name.
+   * @param {Object} context The context object.
+   *
+   * @callback {Function} callback Callback function.
+   * @param {Error} err Error object.
+   * @param {Boolean} isInRole True if the principal is in the specified role.
    */
   Role.isInRole = function(role, context, callback) {
     if (!(context instanceof AccessContext)) {
@@ -317,13 +320,12 @@ module.exports = function(Role) {
   };
 
   /**
-   * List roles for a given principal
-   * @param {Object} context The security context
-   * @param {Function} callback
+   * List roles for a given principal.
+   * @param {Object} context The security context.
    *
-   * @callback {Function} callback
-   * @param {Error=} err
-   * @param {String[]} roles An array of role ids
+   * @callback {Function} callback Callback function.
+   * @param {Error} err Error object.
+   * @param {String[]} roles An array of role IDs
    */
   Role.getRoles = function(context, callback) {
     if (!(context instanceof AccessContext)) {