Extract long remarks (dotnet#9535)

Author: gewarren

add/media/aboutgdip05-art10.gif

@@ -22,37 +22,7 @@
   </Attributes>
   <Docs>
     <summary>Designates a class as an entity class that is associated with a database table.</summary>
-    <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- Use this attribute to designate a class as an entity class that is associated with a database table or view. LINQ to SQL treats classes that have the <xref:System.Data.Linq.Mapping.TableAttribute> attribute as persistent classes.  
-  
- LINQ to SQL supports only single-table mapping. That is, an entity class must be mapped to exactly one database table, and you cannot map a database table to multiple classes at the same time.  
-  
- You can use the <xref:System.Data.Linq.Mapping.TableAttribute.Name%2A> property of the <xref:System.Data.Linq.Mapping.TableAttribute> attribute to specify a name for the table, and you can optionally use the schema name to qualify a table name. If you do not specify a name by using the <xref:System.Data.Linq.Mapping.TableAttribute.Name%2A> property, the table name is assumed to be the same as the class name.  
-  
-## Schema-qualified Names  
- You can optionally use the schema name to qualify a table name. By default, the token to the left of the first period in the <xref:System.Data.Linq.Mapping.TableAttribute.Name%2A> string is considered to be the schema name. The remainder of the name is considered to be the table name. The provider quotes the table name as appropriate. For example, the LINQ to SQL provider for SQL Server makes sure that brackets are used at least where they are needed.  
-  
-> [!NOTE]
->  In some cases, you must explicitly quote attributes because the SQL Server provider cannot auto-quote. The following table shows some examples.  
-  
-|Case|Example: Identifier Name|Example: Expected String in Attributes|Otherwise…|  
-|----------|------------------------------|--------------------------------------------|----------------|  
-|Schema name contains a period|Schema: "A.B"<br /><br /> Table: "C"|"[A.B].C"|The first period is assumed to separate the schema name from the table name.|  
-|Schema/Table name starts with `@`|"@SomeName"|"[@SomeName]"|Assumed to be a parameter name.|  
-|Schema starts with `[` and ends with `]`|"[Schema.Table]"|"[[Schema].[Table]]]"|The unquoted identifier resembles a quoted identifier.|  
-|Table starts with `[` and ends with `]`|"[Table]"|"[[Table]]]"|The unquoted identifier resembles a quoted identifier.|  
-  
-   
-  
-## Examples  
- :::code language="csharp" source="~/snippets/csharp/System.Data.Linq.Mapping/TableAttribute/Overview/Program.cs" id="Snippet1":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqCustomize/vb/Module1.vb" id="Snippet1":::  
-  
- ]]></format>
-    </remarks>
+    <remarks>For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-data-linq-mapping-tableattribute">Supplemental API remarks for TableAttribute</see>.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -109,22 +79,22 @@
         <summary>Gets or sets the name of the table or view.</summary>
         <value>By default, the value is the same as the name of the class.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- If you do not specify a name by using <xref:System.Data.Linq.Mapping.TableAttribute.Name%2A>, the table name is assumed to be the same as the class name.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ If you do not specify a name by using <xref:System.Data.Linq.Mapping.TableAttribute.Name%2A>, the table name is assumed to be the same as the class name.
+
 > [!NOTE]
->  You can optionally use a schema name to qualify the table name (for example, Schema3.Table5). By default, the token to the left of the first period in the <xref:System.Data.Linq.Mapping.TableAttribute.Name%2A> string is considered to be the schema name, and the rest to be the table name.  
-  
- In the following example, the default table name, `Customer`, is changed to `Customers`.  
-  
-   
-  
-## Examples  
+>  You can optionally use a schema name to qualify the table name (for example, Schema3.Table5). By default, the token to the left of the first period in the <xref:System.Data.Linq.Mapping.TableAttribute.Name%2A> string is considered to be the schema name, and the rest to be the table name.
+
+ In the following example, the default table name, `Customer`, is changed to `Customers`.
+
+
+
+## Examples
  :::code language="csharp" source="~/snippets/csharp/System.Data.Linq.Mapping/TableAttribute/Overview/Program.cs" id="Snippet1":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqCustomize/vb/Module1.vb" id="Snippet1":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqCustomize/vb/Module1.vb" id="Snippet1":::
+
  ]]></format>
         </remarks>
       </Docs>

add/media/aboutgdip05-art12.gif

@@ -16,73 +16,7 @@
   <Interfaces />
   <Docs>
     <summary>Provides for immediate loading and filtering of related data.</summary>
-    <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
-  
-## General  
- When you query for an object, you actually retrieve only the object you requested. The *related* objects are not automatically fetched at the same time. (For more information, see [Querying Across Relationships](/dotnet/framework/data/adonet/sql/linq/querying-across-relationships).)  
-  
- The <xref:System.Data.Linq.DataLoadOptions> class provides two methods to achieve immediate loading of specified related data. The <xref:System.Data.Linq.DataLoadOptions.LoadWith%2A> method allows for immediate loading of data related to the main target. The <xref:System.Data.Linq.DataLoadOptions.AssociateWith%2A> method allows for filtering related objects.  
-  
-## Rules  
- Note the following rules regarding <xref:System.Data.Linq.DataLoadOptions> usage:  
-  
--   Assigning a <xref:System.Data.Linq.DataLoadOptions> to a <xref:System.Data.Linq.DataContext> after the first query has been executed generates an exception.  
-  
--   Modifying a <xref:System.Data.Linq.DataLoadOptions> after it has been assigned to a <xref:System.Data.Linq.DataContext> generates an exception  
-  
-## Cycle Handling  
- <xref:System.Data.Linq.DataLoadOptions.LoadWith%2A> and <xref:System.Data.Linq.DataLoadOptions.AssociateWith%2A> directives must not create cycles. The following represent examples of such graphs:  
-  
--   Example 1: Self recursive  
-  
-    -   `dlo.LoadWith<Employee>(e => e.Reports);`  
-  
--   Example 2: Back-pointers  
-  
-    -   `dlo.LoadWith <Customer>(c => C.Orders);`  
-  
-    -   `dlo.LoadWith <Order>(o => o.Customer);`  
-  
--   Example 3: Longer cycles  
-  
-     Although this should not occur in a well-normalized model, it is possible.  
-  
-    -   `dlo.LoadWith <A>(a => a.Bs);`  
-  
-    -   `dlo.LoadWith <B>(b => b.Cs);`  
-  
-    -   `dlo.LoadWith <C>(c => c.As);`  
-  
--   Example 4: Self recursive subQueries  
-  
-    -   `dlo.AssociateWith<A>(a=>a.As.Where(a=>a.Id=33));`  
-  
--   Example 5: Longer recursive subqueries  
-  
-    -   `dlo.AssociateWith<A>(a=>a.Bs.Where(b=>b.Id==3));`  
-  
-    -   `dlo.AssociateWith<B>(b=>b.As.Where(a=>a.Id==3));`  
-  
- The following are some general rules that help you understand what occurs in these scenarios.  
-  
- **LoadWith** Each call to <xref:System.Data.Linq.DataLoadOptions.LoadWith%2A> checks whether cycles have been introduced into the graph. If there are, as in Examples 1, 2, and 3, an exception is thrown.  
-  
- **AssociateWith** The engine at run time does not apply the existing SubQuery clauses to the relationship inside the expression.  
-  
--   In Example 4, the `Where` clause is executed against all `A`, not just the ones sub-filtered by the SubQuery expression itself (because that would be recursive)  
-  
--   In Example 5, the first `Where` clause is applied to all the `B`s, even though there are subqueries on `B`. The second `Where` clause is applied to all the `A`s even though there are subqueries on `A`.  
-  
-   
-  
-## Examples  
- When you retrieve `Customers` from the Northwind sample database, you can use <xref:System.Data.Linq.DataLoadOptions> to specify that `Orders` is also to be retrieved. You can even specify which subset of `Orders` to retrieve.  
-  
- ]]></format>
-    </remarks>
+    <remarks>For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-data-linq-dataloadoptions">Supplemental API remarks for DataLoadOptions</see>.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -123,37 +57,37 @@
         <Parameter Name="expression" Type="System.Linq.Expressions.LambdaExpression" />
       </Parameters>
       <Docs>
-        <param name="expression">Identifies the query to be used on a particular one-to-many field or property. Note the following:  
-  
- If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown.  
-  
- If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows:  
-  
- Where  
-  
- OrderBy  
-  
- ThenBy  
-  
- OrderByDescending  
-  
- ThenByDescending  
-  
+        <param name="expression">Identifies the query to be used on a particular one-to-many field or property. Note the following:
+
+ If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown.
+
+ If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows:
+
+ Where
+
+ OrderBy
+
+ ThenBy
+
+ OrderByDescending
+
+ ThenByDescending
+
  Take
         </param>
         <summary>Filters the objects retrieved for a particular relationship.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- In the following example, the inner loop iterates only over those `Orders` that have not been shipped today.  
-  
-   
-  
-## Examples  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ In the following example, the inner loop iterates only over those `Orders` that have not been shipped today.
+
+
+
+## Examples
  :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/DataLoadOptions/AssociateWith/program.cs" id="Snippet1":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet1":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet1":::
+
  ]]></format>
         </remarks>
       </Docs>
@@ -181,42 +115,42 @@
         <Parameter Name="expression" Type="System.Linq.Expressions.Expression&lt;System.Func&lt;T,System.Object&gt;&gt;" />
       </Parameters>
       <Docs>
-        <typeparam name="T">The type that is queried against.  
-  
+        <typeparam name="T">The type that is queried against.
+
  If the type is unmapped, an exception is thrown.</typeparam>
-        <param name="expression">Identifies the query to be used on a particular one-to-many field or property. Note the following:  
-  
- If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown.  
-  
- If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows:  
-  
- Where  
-  
- OrderBy  
-  
- ThenBy  
-  
- OrderByDescending  
-  
- ThenByDescending  
-  
+        <param name="expression">Identifies the query to be used on a particular one-to-many field or property. Note the following:
+
+ If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown.
+
+ If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows:
+
+ Where
+
+ OrderBy
+
+ ThenBy
+
+ OrderByDescending
+
+ ThenByDescending
+
  Take
         </param>
         <summary>Filters objects retrieved for a particular relationship.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- For information about how to avoid cycles, see <xref:System.Data.Linq.DataLoadOptions>.  
-  
-   
-  
-## Examples  
- In the following example, the inner loop iterates only over those `Orders` that have not been shipped today.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ For information about how to avoid cycles, see <xref:System.Data.Linq.DataLoadOptions>.
+
+
+
+## Examples
+ In the following example, the inner loop iterates only over those `Orders` that have not been shipped today.
+
  :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/DataLoadOptions/AssociateWith/program.cs" id="Snippet1":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet1":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet1":::
+
  ]]></format>
         </remarks>
       </Docs>
@@ -296,17 +230,17 @@
         <param name="expression">A lambda expression that identifies the related material.</param>
         <summary>Retrieves specified data related to the main target by using a lambda expression.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- In the following example, all the `Orders` for all the `Customers` who are located in London are retrieved when the query is executed. As a result, successive access to the `Orders` property on a `Customer` object does not trigger a new database query.  
-  
-   
-  
-## Examples  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ In the following example, all the `Orders` for all the `Customers` who are located in London are retrieved when the query is executed. As a result, successive access to the `Orders` property on a `Customer` object does not trigger a new database query.
+
+
+
+## Examples
  :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/DataLoadOptions/AssociateWith/program.cs" id="Snippet2":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet2":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet2":::
+
  ]]></format>
         </remarks>
       </Docs>
@@ -334,29 +268,29 @@
         <Parameter Name="expression" Type="System.Linq.Expressions.Expression&lt;System.Func&lt;T,System.Object&gt;&gt;" />
       </Parameters>
       <Docs>
-        <typeparam name="T">Type that is queried against.  
-  
+        <typeparam name="T">Type that is queried against.
+
  If this type is unmapped, an exception is thrown.</typeparam>
-        <param name="expression">Identifies the field or property to be retrieved.  
-  
+        <param name="expression">Identifies the field or property to be retrieved.
+
  If the expression does not identify a field or property that represents a one-to-one or one-to-many relationship, an exception is thrown.</param>
         <summary>Specifies which sub-objects to retrieve when a query is submitted for an object of type T.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- You cannot specify the loading of two levels of relationships (for example, `Orders.OrderDetails`). In these scenarios you must specify two separate <xref:System.Data.Linq.DataLoadOptions.LoadWith%2A> methods.  
-  
- To avoid cycling, see Remarks section in <xref:System.Data.Linq.DataLoadOptions>.  
-  
-   
-  
-## Examples  
- In the following example, all the `Orders` for all the `Customers` who are located in London are retrieved when the query is executed. As a result, successive access to the `Orders` property on a `Customer` object does not trigger a new database query.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ You cannot specify the loading of two levels of relationships (for example, `Orders.OrderDetails`). In these scenarios you must specify two separate <xref:System.Data.Linq.DataLoadOptions.LoadWith%2A> methods.
+
+ To avoid cycling, see Remarks section in <xref:System.Data.Linq.DataLoadOptions>.
+
+
+
+## Examples
+ In the following example, all the `Orders` for all the `Customers` who are located in London are retrieved when the query is executed. As a result, successive access to the `Orders` property on a `Customer` object does not trigger a new database query.
+
  :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/DataLoadOptions/AssociateWith/program.cs" id="Snippet2":::
- :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet2":::  
-  
+ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet2":::
+
  ]]></format>
         </remarks>
       </Docs>