1.1 --- a/json/src/main/java/org/apidesign/html/json/spi/Proto.java	Sun Jan 05 21:36:33 2014 +0100
     1.2 +++ b/json/src/main/java/org/apidesign/html/json/spi/Proto.java	Sun Jan 05 22:08:25 2014 +0100
     1.3 @@ -108,20 +108,45 @@
     1.4          locked = false;
     1.5      }
     1.6      
     1.7 +    /** Whenever model changes a property. It should notify the
     1.8 +     * associated technology by calling this method.
     1.9 +     * 
    1.10 +     *@param propName name of the changed property
    1.11 +     */
    1.12      public void valueHasMutated(String propName) {
    1.13          if (ko != null) {
    1.14              ko.valueHasMutated(propName);
    1.15          }
    1.16      }
    1.17      
    1.18 +    /** Initializes the associated model in the current {@link #getContext() context}.
    1.19 +     * In case of <em>knockout.js</em> technology, applies given bindings 
    1.20 +     * of the current model to the <em>body</em> element of the page.
    1.21 +     */
    1.22      public void applyBindings() {
    1.23          initBindings().applyBindings();
    1.24      }
    1.25      
    1.26 +    /** Invokes the provided runnable in the {@link #getContext() context}
    1.27 +     * of the browser. If the caller is already on the right thread, the
    1.28 +     * <code>run.run()</code> is invoked immediately and synchronously. 
    1.29 +     * Otherwise the method returns immediately and the <code>run()</code>
    1.30 +     * method is performed later
    1.31 +     * 
    1.32 +     * @param run the action to execute
    1.33 +     */
    1.34      public void runInBrowser(Runnable run) {
    1.35          JSON.runInBrowser(context, run);
    1.36      }
    1.37  
    1.38 +    /** Initializes the provided collection with a content of the <code>array</code>.
    1.39 +     * The initialization can only be done soon after the the collection 
    1.40 +     * is created, otherwise an exception is throw
    1.41 +     * 
    1.42 +     * @param to the collection to initialize (assumed to be empty)
    1.43 +     * @param array the array to add to the collection
    1.44 +     * @throws IllegalStateException if the system has already been initialized
    1.45 +     */
    1.46      public void initTo(Collection<?> to, Object array) {
    1.47          if (ko != null) {
    1.48              throw new IllegalStateException();
    1.49 @@ -132,11 +157,27 @@
    1.50              JSONList.init(to, array);
    1.51          }
    1.52      }
    1.53 -    
    1.54 +
    1.55 +    /** Takes an object representing JSON result and extract some of its
    1.56 +     * properties. It is assumed that the <code>props</code> and
    1.57 +     * <code>values</code> arrays have the same length.
    1.58 +     * 
    1.59 +     * @param json the JSON object (actual type depends on the associated
    1.60 +     *   {@link Technology})
    1.61 +     * @param props list of properties to extract
    1.62 +     * @param values array that will be filled with extracted values
    1.63 +     */
    1.64      public void extract(Object json, String[] props, Object[] values) {
    1.65          JSON.extract(context, json, props, values);
    1.66      }
    1.67 -    
    1.68 +
    1.69 +    /** Converts raw JSON <code>data</code> into a Java {@link Model} class.
    1.70 +     * 
    1.71 +     * @param <T> type of the model class
    1.72 +     * @param modelClass the type of the class to create
    1.73 +     * @param data the raw JSON data
    1.74 +     * @return newly created instance of the model class
    1.75 +     */
    1.76      public <T> T read(Class<T> modelClass, Object data) {
    1.77          return JSON.read(context, modelClass, data);
    1.78      }
    1.79 @@ -219,10 +260,25 @@
    1.80      public void wsSend(Object webSocket, String url, Object data) {
    1.81          ((JSON.WS)webSocket).send(context, url, data);
    1.82      }
    1.83 -    
    1.84 +
    1.85 +    /** Converts raw data (one of its properties) to string representation.
    1.86 +     * 
    1.87 +     * @param data the object
    1.88 +     * @param propName the name of object property or <code>null</code>
    1.89 +     *   if the whole object should be converted
    1.90 +     * @return the string representation of the object or its property
    1.91 +     */
    1.92      public String toString(Object data, String propName) {
    1.93          return JSON.toString(context, data, propName);
    1.94      }
    1.95 +    
    1.96 +    /** Converts raw data (one of its properties) to a number representation.
    1.97 +     * 
    1.98 +     * @param data the object
    1.99 +     * @param propName the name of object property or <code>null</code>
   1.100 +     *   if the whole object should be converted
   1.101 +     * @return the number representation of the object or its property
   1.102 +     */
   1.103      public Number toNumber(Object data, String propName) {
   1.104          return JSON.toNumber(context, data, propName);
   1.105      }