Improvements to JSDoc comments

lib/models/email.js

@@ -18,11 +18,11 @@ var properties = {
  * 
  * **Properties**
  * 
- * - `to` - **{ String }** **required**
+ * - `to` - String (required)
- * - `from` - **{ String }** **required**
+ * - `from` - String (required)
- * - `subject` - **{ String }** **required**
+ * - `subject` - String (required)
- * - `text` - **{ String }** 
+ * - `text` - String
- * - `html` - **{ String }** 
+ * - `html` - String
  *
  * @class
  * @inherits {Model}
@@ -35,19 +35,24 @@ var Email = module.exports = Model.extend('Email', properties);
  *
  * Example Options:
  *
- * ```json
+ * ```js
  * {
- *   from: "Fred Foo ✔ <foo@blurdybloop.com>", // sender address
+ *   from: "Fred Foo <foo@blurdybloop.com>", // sender address
  *   to: "bar@blurdybloop.com, baz@blurdybloop.com", // list of receivers
- *   subject: "Hello ✔", // Subject line
+ *   subject: "Hello", // Subject line
- *   text: "Hello world ✔", // plaintext body
+ *   text: "Hello world", // plaintext body
- *   html: "<b>Hello world ✔</b>" // html body
+ *   html: "<b>Hello world</b>" // html body
  * }
  * ```
  *
  * See https://github.com/andris9/Nodemailer for other supported options.
  *
- * @param {Object} options
+ * @options {Object} options See below
+ * @prop {String} from Senders's email address
+ * @prop {String} to List of one or more recipient email addresses (comma-delimited)
+ * @prop {String} subject Subject line
+ * @prop {String} text Body text
+ * @prop {String} html Body HTML (optional)
  * @param {Function} callback Called after the e-mail is sent or the sending failed
  */