Port System.Runtime.InteropServices.Javascript docs to RC1 (#8390)

* System.Runtime.InteropServices.Javascript RC1

* First batch of suggestions by gewarren

Co-authored-by: Genevieve Warren <[email protected]>

* Next batch of suggestions by gewarren.

* Apply suggestions from code review

* It's -> This API is

* Apply suggestions from code review

Co-authored-by: Ankit Jain <[email protected]>
Co-authored-by: Genevieve Warren <[email protected]>

* Update xml/System.Runtime.InteropServices.JavaScript/JSExportAttribute.xml

Co-authored-by: Ankit Jain <[email protected]>

Co-authored-by: carlossanlop <[email protected]>
Co-authored-by: Genevieve Warren <[email protected]>
Co-authored-by: Ankit Jain <[email protected]>

Author: 3 people

xml/System.Runtime.InteropServices.JavaScript/JSException.xml

@@ -20,7 +20,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Represents an exception initiated from the JavaScript interop code.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -40,8 +40,8 @@
         <Parameter Name="msg" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="msg">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="msg">The message that describes the error.</param>
+        <summary>Initializes a new instance of the JSException class with a specified error message.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Runtime.InteropServices.JavaScript/JSExportAttribute.xml

@@ -24,8 +24,13 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Indicates that a source generator should export the attributed method to JavaScript and create thunks necessary to marshal its arguments and any return value or thrown exception.</summary>
+    <remarks>
+        <para>For marshaling arguments of complex types <see cref="T:System.Runtime.InteropServices.JavaScript.JSMarshalAsAttribute`1" />.</para>
+        <para>This attribute is meaningless if the source generator associated with it is not enabled.</para>
+        <para>The current built-in source generator only supports C# and only supplies an implementation when applied to static, non-partial, or non-generic methods.</para>
+        <para>Exported methods cannot be trimmed by the linker.</para>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -41,7 +46,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Runtime.InteropServices.JavaScript.JSExportAttribute" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Runtime.InteropServices.JavaScript/JSFunctionBinding.xml

@@ -28,7 +28,8 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Represents a bound imported or exported JavaScript function and contains information necessary to invoke it.
+            This API supports JSImport infrastructure and is not intended to be used directly from your code.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -73,7 +74,8 @@
         <param name="functionName">To be added.</param>
         <param name="moduleName">To be added.</param>
         <param name="signatures">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Locates and binds a JavaScript function given name and module so that it can later be invoked by managed callers.
+            This API supports JSImport infrastructure and is not intended to be used directly from your code.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -102,7 +104,8 @@
         <param name="fullyQualifiedName">To be added.</param>
         <param name="signatureHash">To be added.</param>
         <param name="signatures">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Binds a specific managed function wrapper so that it can later be invoked by JavaScript callers.
+            This API supports JSImport infrastructure and is not intended to be used directly from your code.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -129,7 +132,8 @@
       <Docs>
         <param name="signature">To be added.</param>
         <param name="arguments">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Invokes a previously bound JavaScript function using the provided span to transport argument and return values.
+            This API supports JSImport infrastructure and is not intended to be used directly from your code.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Runtime.InteropServices.JavaScript/JSHost.xml

@@ -20,7 +20,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Represents the JavaScript host environment where the .NET runtime is currently operating.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -40,7 +40,7 @@
         <ReturnType>System.Runtime.InteropServices.JavaScript.JSObject</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Returns a proxy for the JavaScript module that contains the .NET runtime.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -61,7 +61,7 @@
         <ReturnType>System.Runtime.InteropServices.JavaScript.JSObject</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Returns a proxy for the <see href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/globalThis">globalThis</see> JavaScript host object.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -86,11 +86,12 @@
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="moduleName">To be added.</param>
-        <param name="moduleUrl">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="moduleName">Globally unique identifier of the ES6 module, which is used by <see cref="M:System.Runtime.InteropServices.JavaScript.JSImportAttribute.#ctor(System.String,System.String)" />.</param>
+        <param name="moduleUrl">The location of the module file.</param>
+        <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+        <summary>Downloads and instantiates an ES6 module from the provided URL, via the JavaScript host's <see href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import">dynamic import API</see>.
+            If a module with the provided <paramref name="moduleName" /> has previously been instantiated, it will be returned instead.</summary>
+        <returns>A proxy for the JavaScript object that contains the module's exports.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Runtime.InteropServices.JavaScript/JSImportAttribute.xml

@@ -24,8 +24,12 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Indicates that the JSImport source generator should create a managed wrapper to invoke a specific imported JavaScript function and marshal its arguments, return values, and exceptions.</summary>
+    <remarks>
+        <para>To configure the marshalling behavior for specific values, <see cref="T:System.Runtime.InteropServices.JavaScript.JSMarshalAsAttribute`1" />.</para>
+        <para>This attribute is meaningless if the source generator associated with it is not enabled.</para>
+        <para>The current built-in source generator only supports C# and only supplies an implementation when applied to static, partial, non-generic methods.</para>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -44,8 +48,8 @@
         <Parameter Name="functionName" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="functionName">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="functionName">The name of the function to be bound in the module. Use dots for nested objects.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Runtime.InteropServices.JavaScript.JSImportAttribute" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -66,9 +70,10 @@
         <Parameter Name="moduleName" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="functionName">To be added.</param>
-        <param name="moduleName">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="functionName">The name of the target JavaScript function. This name will be used as a key to locate the function in the module.
+            Functions nested inside of objects can be referred to by using the dot operator to connect one or more names.</param>
+        <param name="moduleName">Globally unique identifier of the ES6 module, if any, that contains the function. The module must be loaded via <see cref="M:System.Runtime.InteropServices.JavaScript.JSHost.ImportAsync(System.String,System.String,System.Threading.CancellationToken)" /> before any attempt to invoke the function.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Runtime.InteropServices.JavaScript.JSImportAttribute" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -88,9 +93,9 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the name of the target JavaScript function. This name will be used as a key to locate the function in the module.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>Functions nested inside of objects can be referred to by using the dot operator to connect one or more names.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ModuleName">
@@ -109,7 +114,7 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the globally unique identifier of the ES6 module, if any, that contains the function. The module must be loaded via <see cref="M:System.Runtime.InteropServices.JavaScript.JSHost.ImportAsync(System.String,System.String,System.Threading.CancellationToken)" /> before any attempt to invoke the function.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>

xml/System.Runtime.InteropServices.JavaScript/JSMarshalAsAttribute`1.xml

@@ -31,8 +31,9 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <typeparam name="T">To be added.</typeparam>
-    <summary>To be added.</summary>
+    <typeparam name="T">One of the types defined in <see cref="T:System.Runtime.InteropServices.JavaScript.JSType" />, for example <see cref="T:System.Runtime.InteropServices.JavaScript.JSType.MemoryView" />.</typeparam>
+    <summary>Specifies the JavaScript type associated with a managed argument or return value.
+            The JSImport generator will use this information to marshal data between the JavaScript and managed environments.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -49,7 +50,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of <see cref="T:System.Runtime.InteropServices.JavaScript.JSMarshalAsAttribute`1" /> configured by generic parameters of <see cref="T:System.Runtime.InteropServices.JavaScript.JSType" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Runtime.InteropServices.JavaScript/JSMarshalerArgument+ArgumentToJSCallback`1.xml

@@ -26,7 +26,8 @@
     <typeparam name="T">To be added.</typeparam>
     <param name="arg">To be added.</param>
     <param name="value">To be added.</param>
-    <summary>To be added.</summary>
+    <summary>Assists in marshalling of Task results and Function arguments.
+            This API is used by JSImport code generator and should not be used by developers in source code.</summary>
     <remarks>To be added.</remarks>
   </Docs>
 </Type>

xml/System.Runtime.InteropServices.JavaScript/JSMarshalerArgument+ArgumentToManagedCallback`1.xml

@@ -26,7 +26,8 @@
     <typeparam name="T">To be added.</typeparam>
     <param name="arg">To be added.</param>
     <param name="value">To be added.</param>
-    <summary>To be added.</summary>
+    <summary>Assists in marshalling of Task results and Function arguments.
+            This API is used by JSImport code generator and should not be used by developers in source code.</summary>
     <remarks>To be added.</remarks>
   </Docs>
 </Type>