 use namespace mx_internal;
 
 /**
- * An instance of this class can manage formatting HTTP request responses and
- * converting their parameters.  HTTPMultiService and HTTPService will expose a
- * serializationFilter property, or you can define one of these statically and register it
- * for a custom resultFormat.  In that case, the resultFormat can be used to choose the
- * SerializationFilter automatically. 
+ * This class is useful for framework developers wishing to plug in or modify the
+ * HTTP services to use a new serialization format.  This allows you to invoke
+ * methods on the service object and control how parameters are mapped to a specific
+ * serialiation format such as XML, JSON, etc.  The SerializationFilter mechanism
+ * allows you to add a new resultFormat as well.
+ * <p>
+ * An instance of this class can manage formatting HTTP requests, responses, and
+ * converting their parameters.  When you use HTTPService or HTTPMultiService, you 
+ * are usually talking to a server which expects the data to be provided in a specific
+ * format - for example, URL encoded values for a type HTML form, XML values or another
+ * serialization format such as JSON.  SerializationFilter 
+ * allows you to customize how HTTPService and HTTPMultiService convert an operation's
+ * parameters into the body of the HTTP request and how the response is converted into
+ * the return value of the operation.  Framework developers can introduce a new serialization
+ * format to the system by providing a new implementation of the SerializationFilter and
+ * use these components and all of the frameworks and tools built on these components
+ * without having to know the details of the format itself.
+ * </p>
+ * <p>
+ * The first thing you do is to extend the SerializationFilter and override one or more
+ * of the conversion methods.   The filter allows you to turn the ordered list of parameters
+ * into a request body, modify the request body, modify the content type used in the
+ * request, modify the actual URL used in the request, and convert the response data into
+ * the result object returned in the result event of the service.
+ * </p>
+ * <p>
+ * There are two ways to specify the SerializationFilter for a particular HTTPService,
+ * or HTTPMultiService.  You can either set the serializationFilter property on the service
+ * or you can statically register a SerializationFilter for a new result format.  If you
+ * use this approach, simply by specifying the resultFormat you can use a pre-registered
+ * SerializationFilter.  So for example, you might register a SerializationFilter for the
+ * "json" type and can then use that filter by setting resultFormat="json".
+ * <p>
+ * Note that HTTPService only provides methods which directly take the request body
+ * and so does not use the "serializeParameters" method.
+ * </p>
  */
 public class SerializationFilter
 {
     // replaces/returns previous with that name or null
     static mx_internal var filterForResultFormatTable:Object = new Object();
+
+    /**
+     * This static function is used to register a new SerializationFilter for a 
+     * particular resultFormat value.  If you call this method once at startup,
+     * you can then just specify the resultFormat property of an HTTPService or HTTPMultiService
+     * to use that serialization filter to make it easier for developers to specify a
+     * format.
+     *
+     * @param resultFormat A custom resultFormat name to be associated with the supplied
+     * SerializationFilter.  
+     * @param filter The SerializationFilter to register.
+     */
     public static function registerFilterForResultFormat(resultFormat:String, filter:SerializationFilter):SerializationFilter
     {
         var old:SerializationFilter = filterForResultFormatTable[resultFormat];


    /**
     * This method is used if you need to take data from the request body object and encode
     * it into the URL string.   It is given the incoming URL.  By default, the incoming
     * URL is returned directly.
     */
    public function serializeURL(operation:AbstractOperation, obj:Object, url:String):String
    {


    /**
     * This method takes the result from the HTTP request in a raw format.  It 
     * can convert it to a more fully typed ActionScript object if desired.  
     * To make the SerializationFilter more general, you can use the resultType or 
     * resultElementType properties of the AbstractOperation provided so your code can 
     * dynamically map the incoming request to the type configured in ActionScript as
     * the return type.
     * <p>
     * Note also that AbstractOperation has a "properties" map which you
     * can use to store additional properties as part of the service invocation
     * in ActionScript to handle the deserialization of a particular type.
     * </p>
     * 
     * @param operation The AbstractOperation which is being invoked.  
     * @param result the raw result as returned from the server.  
     * @return the converted result which will then be supplied in the result event
     * for the service.
     */
    public function deserializeResult(operation:AbstractOperation, result:Object):Object
    {
