Added helpInfo docs for JSO restrictions and for restrictions on accessing
longs from JSNI. This fills in the place holders posted in revision 2344.
Review by: scottb (TBR)
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@2348 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/distro-source/core/src/doc/helpInfo/jsoRestrictions.html b/distro-source/core/src/doc/helpInfo/jsoRestrictions.html
index cf69a7f..88addf8 100644
--- a/distro-source/core/src/doc/helpInfo/jsoRestrictions.html
+++ b/distro-source/core/src/doc/helpInfo/jsoRestrictions.html
@@ -1,9 +1,53 @@
<html>
- <head>
- <meta http-equiv="content-type" content="text/html; charset=UTF-8">
- <title>Restrictions on subclasses of JavaScriptObject</title>
- </head>
- <body>
- TODO(spoon): write some doc!
- </body>
+<head>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+<title>Restrictions on subclasses of JavaScriptObject</title>
+</head>
+<body>
+
+<p>Subclasses of JavaScriptObject represent a view of a JavaScript object
+from Java. Such classes must conform to a number of restrictions so
+that the compiler can implement them. This page lists those restrictions.
+
+<p>In the following, "JSO class" means any subclass of
+<code>JavaScriptObject</code>. Rationales are written <em>like
+this</em>.
+
+<ol>
+
+ <li> All instance methods on JSO classes must be explicitly marked
+ final. <em>This enforces on the developer the restriction of no
+ polymorphism, because all final instance methods can be dispatched
+ statically.</em>
+
+ <li> JSO classes cannot implement interfaces that define
+ methods. <em>This prevents virtual calls that would arise by
+ upcasting to the interface and then calling through the interface.
+ The programmer should instead use a wrapper, for example using
+ <code>Comparator</code> instead of implementing
+ <code>Comparable</code>.</em>
+
+ <li> No instance methods on JSO classes may override another
+ method. <em>This catches accidents where JSO itself did not finalize
+ some method from its superclass.</em>
+
+ <li> JSO classes cannot have instance fields. <em>The fields would
+ have no place to live in web mode. Programmers should instead make
+ an explicit wrapper class and put the fields there.</em>
+
+ <li> Nested JSO classes must be static. <em>The implicit
+ <code>this</code> fields of a non-static inner class has the same
+ problems as an explicit field.</em>
+
+ <li> "new" operations cannot be used with JSO classes. <em>This
+ avoids ever being able to try to instantiate JSO objects using the
+ new keyword. New JSO instances can only come from JSNI, as in
+ previous versions of GWT.</em>
+
+ <li> Every JSO class must have precisely one constructor, and it must
+ be protected, empty, and no-argument.
+
+</ol>
+
+</body>
</html>
diff --git a/distro-source/core/src/doc/helpInfo/longJsniRestriction.html b/distro-source/core/src/doc/helpInfo/longJsniRestriction.html
index fdaaac9..0c881b1 100644
--- a/distro-source/core/src/doc/helpInfo/longJsniRestriction.html
+++ b/distro-source/core/src/doc/helpInfo/longJsniRestriction.html
@@ -4,6 +4,39 @@
<title>Restrictions on long values with JSNI</title>
</head>
<body>
- TODO(spoon): write some doc!
+
+ <p>The Java <code>long</code> type cannot be represented in JavaScript
+ as a numeric type, so GWT emulates it using an opaque data structure.
+ This means that JSNI methods cannot process a <code>long</code> as a
+ numeric type. The compiler therefore disallows, by default, directly
+ accessing a <code>long</code> from JSNI: JSNI methods cannot have
+ <code>long</code> as a parameter type or a return type, and they
+ cannot access a <code>long</code> using a JSNI reference. If you
+ find yourself wanting to pass a <code>long</code> into or out of a
+ JSNI method, here are some options:
+
+ <ol>
+
+ <li> For numbers that fit into type <code>double</code>, use type
+ <code>double</code> instead of type <code>long</code>.
+
+ <li> For computations that require the full <code>long</code>
+ semantics, rearrange the code so that the computations happen in
+ Java instead of in JavaScript. That way they will use the
+ <code>long</code> emulation.
+
+ <li> For values meant to be passed through unchanged to Java code,
+ wrap the value in a <code>long</code>. There are no restrictions
+ on type <code>long</code> with JSNI methods.
+
+ <li> If you are sure you know what you are doing, you can add the
+ annotation
+ <code>com.google.gwt.core.client.UnsafeNativeLong</code> to the
+ method. The compiler will then allow you to pass a
+ <code>long</code> into and out of JavaScript. It will still be an
+ opaque data type, however, so the only thing you will be able to
+ do with it will be to pass it back to Java.
+
+ </ol>
</body>
</html>
