fixup! 93109df

expand comments describing converter methods

lib/remote-objects.js

@@ -710,8 +710,10 @@ RemoteObjects.prototype.getScope = function(ctx, method) {
  *
  * ```
  * remotes.defineType('MyType', {
+ *   // Convert the raw "value" coming typically from JSON.
+ *   // Use the remoting context in "ctx" to access the type registry and
+ *   // other request-related information.
  *   fromTypedValue: function(ctx, value) {
- *     // use the val and ctx objects to return the concrete value
  *     if (value === undefined || value === null)
  *       return { value: value };
  *
@@ -720,19 +722,25 @@ RemoteObjects.prototype.getScope = function(ctx, method) {
  *     return error ? { error: error } : { value: value };
  *   },
  *
+ *   // Apply any coercion needed to convert values coming from
+ *   // string-only sources like HTTP headers and query string.
+ *   //
+ *   // A sloppy value is one of:
+ *   //  - a string
+ *   //  - an array containing sloppy values
+ *   //  - an object where property values are sloppy
  *   fromSloppyValue: function(ctx, value) {
- *     // use the val and ctx objects to return the concrete value
- *     // apply any coercion needed to convert values coming from
- *     // string-only sources like HTTP headers and query string.
  *     var objectConverter = ctx.typeRegistry.getConverter('object');
  *     var result = objectConverter.fromSloppyString(ctx, value);
  *     return result.error ? result : this.fromTypedValue(ctx, result.value);
  *   },
  *
+ *   // Perform basic validation of the value. Validations are required to be
+ *   // synchronous.
  *   validate: function(ctx, value) {
  *     if (value === undefined || value === null)
  *       return null;
- *     if (typeof value !== 'object' || !value instanceof MyType) {
+ *     if (typeof value !== 'object' || !(value instanceof MyType) {
  *       return new Error('Value is not an instance of MyType.');
  *     }
  *     return null;