Add documentation for allowInterop and allowInteropCaptureThis

sdk/lib/js/dartium/js_dartium.dart

Index: sdk/lib/js/dartium/js_dartium.dart
diff --git a/sdk/lib/js/dartium/js_dartium.dart b/sdk/lib/js/dartium/js_dartium.dart
index f2ab9c465602b7763ec5daa9a492aa34ac55be68..dd2add3b6abddacad3e4d091f8ee0c2ead9713cf 100644
--- a/sdk/lib/js/dartium/js_dartium.dart
+++ b/sdk/lib/js/dartium/js_dartium.dart
@@ -1160,13 +1160,29 @@ Function _wrapAsDebuggerVarArgsFunction(JsFunction jsFunction) =>
         a9 = _UNDEFINED, a10 = _UNDEFINED]) => jsFunction._applyDebuggerOnly(
             _stripUndefinedArgs([a1, a2, a3, a4, a5, a6, a7, a8, a9, a10]));
 
-// This method is a no-op in Dartium.
+// The allowInterop method is a no-op in Dartium.
 // TODO(jacobr): tag methods so we can throw if a Dart method is passed to
 // JavaScript using the new interop without calling allowInterop.
+
+/// Returns a wrapper around function [f] that can be called from JavaScript
+/// using the package:js Dart-JavaScript interop.

[kevmoo, 2015/10/27 19:56:18]

Add an empty line between first and second sentence

+/// For performance reasons in Dart2Js, by default Dart functions cannot be
+/// passed directly to JavaScript unless this method is called to create
+/// a Function compatible with both Dart and JavaScript.
+/// Calling this method repeatedly on a function will return the same function.
+/// The [Function] returned by this method can be used from both Dart and
+/// JavaScript. We may remove the need to call this method completely in the
+/// future if Dart2Js is refactored so that its function calling conventions
+/// are more compatible with JavaScript.
 Function allowInterop(Function f) => f;
 
 Expando<JsFunction> _interopCaptureThisExpando = new Expando<JsFunction>();
 
+/// See the documention for [allowInterop]. This method should only be used with

[kevmoo, 2015/10/27 19:56:18]

Re-order per discussion

+/// package:js Dart-JavaScript interop.
+/// Returns a [Function] that when called from JavaScript captures its 'this'
+/// binding and calls [f] with the value of this passed as the first argument.
+/// When called from Dart, [null] will be passed as the first argument.
 Function allowInteropCaptureThis(Function f) {
   if (f is JsFunction) {
     // Behavior when the function is already a JS function is unspecified.