1.1 --- a/json/src/main/java/net/java/html/json/Model.java	Wed Dec 09 21:39:13 2015 +0100
     1.2 +++ b/json/src/main/java/net/java/html/json/Model.java	Wed Dec 09 22:13:16 2015 +0100
     1.3 @@ -280,9 +280,71 @@
     1.4       * data.hello();
     1.5       * <b>assert</b> data.getMessage().equals("Hello 3 times!");
     1.6       * </pre>
     1.7 +     * <p>
     1.8       * The methods annotated by {@link ComputedProperty} need to remain static, as 
     1.9       * they are supposed to be <em>pure</em> functions (e.g. depend only on their parameters)
    1.10       * and shouldn't use any internal state.
    1.11 +     * </p>
    1.12 +     * <p><b>How do I initialize private values?</b>
    1.13 +     * The implementation class (the one annotated by {@link Model @Model} annotation) 
    1.14 +     * needs to have accessible default constructor. That constructor is used to 
    1.15 +     * create the instance. Obviously such constructor does not have 
    1.16 +     * any parameters, so no initialization is possible.
    1.17 +     * </p>
    1.18 +     * <p>
    1.19 +     * Later one can, however, call any {@link ModelOperation @ModelOperation}
    1.20 +     * method and pass in additional configuration parameters. In the above 
    1.21 +     * example it should be possible add
    1.22 +     * </p>
    1.23 +     * <pre>
    1.24 +     * {@link ModelOperation @ModelOperation} <b>void</b> init(Data model, int count) {
    1.25 +     *   <b>this</b>.count = count;
    1.26 +     * }
    1.27 +     * </pre><p>
    1.28 +     * and then one can initialize the model using the <code>init</code> as:
    1.29 +     * </p>
    1.30 +     * <pre>
    1.31 +     * Data data = <b>new</b> Data();
    1.32 +     * data.init(2);
    1.33 +     * data.increment();
    1.34 +     * data.hello();
    1.35 +     * <b>assert</b> data.getMessage().equals("Hello 3 times!");
    1.36 +     * </pre><p>
    1.37 +     * Why there has to be default constructor? Because instances of 
    1.38 +     * classes generated by {@link Model @Model annotation} may be constructed
    1.39 +     * by the system as wrappers around existing JavaScript objects - then
    1.40 +     * there is nobody to provide additional parameters at construction time.
    1.41 +     * </p>
    1.42 +     * <p><b>How do I read private values?</b>
    1.43 +     * The methods annotated by {@link ModelOperation} must return <code>void</code>
    1.44 +     * (as they can run asynchronously) and as such they aren't suitable for
    1.45 +     * returning values back to the caller. In case something like that is
    1.46 +     * needed, one can use the approach of the <code>hello</code> method - e.g.
    1.47 +     * set value of some {@link Property property} that has a getter:
    1.48 +     * </p>
    1.49 +     * <pre>
    1.50 +     * data.hello();
    1.51 +     * <b>assert</b> data.getMessage().equals("Hello 3 times!");
    1.52 +     * </pre><p>
    1.53 +     * Or one can use actor-like callbacks. Define callback interface and
    1.54 +     * use it in a {@link ModelOperation @ModelOperation} method:
    1.55 +     * </p>
    1.56 +     * <pre>
    1.57 +     * <b>public interface</b> ReadCount {
    1.58 +     *   <b>public void</b> notifyCount(int count);
    1.59 +     * }
    1.60 +     * {@link ModelOperation @ModelOperation} <b>void</b> readCount(Data model, ReadCount callback) {
    1.61 +     *   callback.readCount(<b>this</b>.count);
    1.62 +     * }
    1.63 +     * Data data = <b>new</b> Data();
    1.64 +     * data.init(2);
    1.65 +     * data.increment();
    1.66 +     * data.readCount(count -&gt; System.out.println("count should be 3: " + count));
    1.67 +     * </pre><p>
    1.68 +     * The provided lambda-function callback may be invoked immediately 
    1.69 +     * or asynchronously as documentation for {@link ModelOperation} 
    1.70 +     * annotation describes.
    1.71 +     * </p>
    1.72       * 
    1.73       * @return <code>true</code> if the model class should keep pointer to
    1.74       *   instance of the implementation class