# HG changeset patch
# User Jaroslav Tulach <jaroslav.tulach@apidesign.org>
# Date 1365589172 -7200
# Node ID df60ba2aeb87ee4cebee4ab76fe595db80d48e21
# Parent  62d77cc38117ce8697794af8b75bb43a43b834a1
Better Javadoc with a sample code

diff -r 62d77cc38117 -r df60ba2aeb87 javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/Model.java
--- a/javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/Model.java	Wed Apr 10 11:43:46 2013 +0200
+++ b/javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/Model.java	Wed Apr 10 12:19:32 2013 +0200
@@ -27,8 +27,9 @@
  * annotated by {@link ComputedProperty} which define derived
  * properties in the model class.
  * <p>
- * The {@link #className() generated class} will have methods
- * to convert the object <code>toJSON</code> and <code>fromJSON</code>.
+ * The {@link #className() generated class}'s <code>toString</code>
+ * converts the state of the object into 
+ * <a href="http://en.wikipedia.org/wiki/JSON">JSON</a> format.
  *
  * @author Jaroslav Tulach <jtulach@netbeans.org>
  */
diff -r 62d77cc38117 -r df60ba2aeb87 javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/OnReceive.java
--- a/javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/OnReceive.java	Wed Apr 10 11:43:46 2013 +0200
+++ b/javaquery/api/src/main/java/org/apidesign/bck2brwsr/htmlpage/api/OnReceive.java	Wed Apr 10 12:19:32 2013 +0200
@@ -22,12 +22,51 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/** Static methods in classes annotated by {@link Model} or {@link Page}
- * can be marked by this annotation establish a JSON communication point.
+/** Static methods in classes annotated by {@link Page}
+ * can be marked by this annotation to establish a 
+ * <a href="http://en.wikipedia.org/wiki/JSON">JSON</a>
+ * communication point.
  * The associated model page then gets new method to invoke a network
- * connection 
+ * connection. Example follows:
+ * 
+ * <pre>
+ * {@link Page @Page}(className="MyModel", xhtml="page.html", properties={
+ *   {@link Property @Property}(name = "people", type=Person.class, array=true)
+ * })
+ * class MyModelImpl {
+ *   {@link Model @Model}(className="Person", properties={
+ *     {@link Property @Property}(name = "firstName", type=String.class),
+ *     {@link Property @Property}(name = "lastName", type=String.class)
+ *   })
+ *   static class PersonImpl {
+ *     {@link ComputedProperty @ComputedProperty}
+ *     static String fullName(String firstName, String lastName) {
+ *       return firstName + " " + lastName;
+ *     }
+ *   }
+ * 
+ *   {@link OnReceive @OnReceive}(url = "{protocol}://your.server.com/person/{name}")
+ *   static void getANewPerson(MyModel m, Person p) {
+ *     {@link Element#alert Element.alert}("Adding " + p.getFullName() + '!');
+ *     m.getPeople().add(p);
+ *   }
+ * 
+ *   // the above will generate method <code>getANewPerson</code> in class <code>MyModel</code>.
+ *   // with <code>protocol</code> and <code>name</code> arguments
+ *   // which asynchronously contacts the server and in case of success calls
+ *   // your {@link OnReceive @OnReceive} with parsed in data
+ * 
+ *   {@link On @On}(event={@link OnEvent#CLICK OnEvent.CLICK}, id="rqst")
+ *   static void requestSmith(MyModel m) {
+ *     m.getANewPerson("http", "Smith");
+ *   }
+ * }
+ * </pre>
+ * When the server returns <code>{ "firstName" : "John", "lastName" : "Smith" }</code>
+ * the browser will show alert message <em>Adding John Smith!</em>.
  * 
  * @author Jaroslav Tulach <jtulach@netbeans.org>
+ * @since 0.6
  */
 @Retention(RetentionPolicy.SOURCE)
 @Target(ElementType.METHOD)