Feedback about the current API design

Dear All

I've sent feedback to the co-editors already. As requested, I summarized the
feedback here.

1. About the RESULT design

   - Chri's has an approach by defining each type of Error as an interface
   with a string member denoting the error message.
   - I proposed another two approaches: First one, use the
   [ExceptionConstant] extend attribute documented at Web IDL specs [1] section
   3.8.3. The [ExceptionConstant] is created to help documenting error code
   like exceptions. Here's the example:
   [ExceptionConsts=FileIOExceptioin]
   module fileio {
       exception FileIOException {
           unsigned short code;
       }

      const unsigned short FILE_NOT_FOUND = 1;
      const unsigned short READ_ERROR = 2;
      const unsinged short WRITE_ERROR = 3;
   }
   - The second approach is refering BONDI [2] which is a Web IDL based
   API sepcification for web runtime applications. In BONDI, the exceptions are
   documented as normal 'interface' other than 'exception', as Web
   IDL 'exception' does not support inheritance. In the design pattern document
   of BONDI [3],  it contains the purpose behind their design. Here's the
   example:
   interface GenericError {
        readonly attribute unsigned short code;
   };

   interface DeviceAPIError : GenericError {
        const unsigned short UNKNOWN_ERROR           = 10000;
        const unsigned short INVALID_ARGUMENT_ERROR  = 10001;
        const unsigned short NOT_FOUND_ERROR         = 10002;
        const unsigned short PENDING_OPERATION_ERROR = 10003;
        const unsigned short IO_ERROR                = 10004;
        const unsigned short NOT_SUPPORTED_ERROR     = 10005;
   };

2. About the array type:

   - As I know, the way to define an array in Web IDL is using the
   sequence<T> type. In the current document, the array is documented as T[].
   Since Web IDL defines the binding to other languages, in order to make our
   API successfully be generated to specific language libraries, we'd better
   follow the exact syntax. Here's an example:
   typedef sequence<Object> ObjectArray
   typedef sequence<DOMString> StringArray

3. About the returnType

   - The question is why we inherit each interface to Unstructured
   interface?


If allowed, let's discuss it in today's meeting.

Best Regards,

Hui

[1] http://www.w3.org/TR/WebIDL/
[2] http://bondi.omtp.org/default.aspx
[3]
http://bondi.omtp.org/1.01/apis/BONDI_Interface_Patterns_v1.0.html#errorhandling