Moved more enum member remarks (#2454)

Ron Petrusha · mairaw · web-flow · commit 91a5c40b86e7 · 2019-05-21T15:29:29.000-07:00
* Moved enum member remarks

* Corrected badly formed XML

* Apply suggestions from code review

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;
diff --git a/xml/System.Data.Common/CatalogLocation.xml b/xml/System.Data.Common/CatalogLocation.xml
@@ -59,15 +59,8 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>Indicates that the position of the catalog name occurs after the schema portion of a fully qualified table name in a text command.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The value of this field and the value of the Start field are mutually exclusive.  
-  
- ]]></format>
-        </remarks>
+        <summary>Indicates that the position of the catalog name occurs after the schema portion of a fully qualified table name in a text command. <c>End</c> and <c>Start</c> are mutually exclusive.</summary>
+        <remarks>To be added.</remarks>
         <related type="Article" href="~/docs/framework/data/adonet/ado-net-overview.md">ADO.NET Overview</related>
       </Docs>
     </Member>
@@ -100,15 +93,8 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>Indicates that the position of the catalog name occurs before the schema portion of a fully qualified table name in a text command.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The value of this field and the value of the End field are mutually exclusive.  
-  
- ]]></format>
-        </remarks>
+        <summary>Indicates that the position of the catalog name occurs before the schema portion of a fully qualified table name in a text command. <c>Start</c> and <c>End</c> are mutually exclusive. </summary>
+        <remarks>To be added.</remarks>
         <related type="Article" href="~/docs/framework/data/adonet/ado-net-overview.md">ADO.NET Overview</related>
       </Docs>
     </Member>
diff --git a/xml/System.Data.Objects/MergeOption.xml b/xml/System.Data.Objects/MergeOption.xml
@@ -19,7 +19,21 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
- The [!INCLUDE[adonet_ef](~/includes/adonet-ef-md.md)] only maintains a single instance of an object with a specific entity key in the cache. The <xref:System.Data.EntityKey> objects are immutable objects that represent object's identity. Entity keys are used to perform identity resolution in the object context. For more information, see [Working with Entity Keys](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/dd283139(v=vs.100)). If an entity with the same identity is already being tracked, the data coming from the data source and the data already in the state manager are merged according to the <xref:System.Data.Objects.MergeOption> of the query.  
+ The Entity Framework only maintains a single instance of an object with a specific entity key in the cache. The <xref:System.Data.EntityKey> objects are immutable objects that represent object's identity. Entity keys are used to perform identity resolution in the object context. For more information, see [Working with Entity Keys](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/dd283139(v=vs.100)). If an entity with the same identity is already being tracked, the data coming from the data source and the data already in the state manager are merged according to the <xref:System.Data.Objects.MergeOption> of the query.  
+
+### Additional information on `MergeOption.PreserveChanges`
+
+ If the state of the entity is <xref:System.Data.EntityState.Unchanged?displayProperty=nameWithType>, the current and original values in the entry are overwritten with data source values. The state of the entity remains <xref:System.Data.EntityState.Unchanged?displayProperty=nameWithType> and no properties are marked as modified.  
+  
+ If the state of the entity is <xref:System.Data.EntityState.Modified?displayProperty=nameWithType>, the current values of modified properties are not overwritten with data source values. The original values of unmodified properties are overwritten with the values from the data source.  
+  
+ In .NET Framework 4, the Entity Framework compares the current values of unmodified properties with the values that were returned from the data source. If the values are not the same, the property is marked as modified.  
+  
+ In .NET Framework 3.5 SP1, the Entity Framework does not mark the property as modified even if the value in the data source is different.  
+  
+ Only modified properties are persisted to the data source when you call <xref:System.Data.Objects.ObjectContext.SaveChanges%2A?displayProperty=nameWithType>.  
+  
+ To preserve the .NET Framework 3.5 SP1 behavior, set <xref:System.Data.Objects.ObjectContextOptions.UseLegacyPreserveChangesBehavior%2A?displayProperty=nameWithType> to `true`. The `PreserveChanges` option can be used to resolve optimistic concurrency exceptions while preserving changes in the local context. For more information, see [Saving Changes and Managing Concurrency](https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)).
   
  ]]></format>
     </remarks>
@@ -107,24 +121,7 @@
       <MemberValue>2</MemberValue>
       <Docs>
         <summary>Objects that do not exist in the object context are attached to the context.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- If the state of the entity is <xref:System.Data.EntityState.Unchanged>, the current and original values in the entry are overwritten with data source values. The state of the entity remains <xref:System.Data.EntityState.Unchanged> and no properties are marked as modified.  
-  
- If the state of the entity is <xref:System.Data.EntityState.Modified>, the current values of modified properties are not overwritten with data source values. The original values of unmodified properties are overwritten with the values from the data source.  
-  
- In the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] version 4, the [!INCLUDE[adonet_ef](~/includes/adonet-ef-md.md)] compares the current values of unmodified properties with the values that were returned from the data source. If the values are not the same, the property is marked as modified.  
-  
- In the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] version 3.5 SP1, the [!INCLUDE[adonet_ef](~/includes/adonet-ef-md.md)] does not mark the property as modified, even if the value in the data source is different.  
-  
- Only modified properties are persisted to the data source when you call <xref:System.Data.Objects.ObjectContext.SaveChanges%2A>.  
-  
- To preserve the 3.5 SP1 behavior, set <xref:System.Data.Objects.ObjectContextOptions.UseLegacyPreserveChangesBehavior%2A> to `true`. The PreserveChanges option can be used to resolve optimistic concurrency exceptions while preserving changes in the local context. For more information, see [Saving Changes and Managing Concurrency](https://msdn.microsoft.com/library/b8378601-4f26-4a05-a24a-f50aeb68610e).  
-  
- ]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
diff --git a/xml/System.Data.OleDb/OleDbType.xml b/xml/System.Data.OleDb/OleDbType.xml
@@ -415,15 +415,11 @@
       </ReturnValue>
       <MemberValue>9</MemberValue>
       <Docs>
-        <summary>A pointer to an <see langword="IDispatch" /> interface (DBTYPE_IDISPATCH). This maps to <see cref="T:System.Object" />.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This data type is not currently supported by ADO.NET. Usage may cause unpredictable results.  
-  
- ]]></format>
-        </remarks>
+        <summary>A pointer to an <see langword="IDispatch" /> interface (DBTYPE_IDISPATCH). This maps to <see cref="T:System.Object" />.
+        
+This data type is not currently supported by ADO.NET. Its usage may cause unpredictable results.        
+        </summary>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Integer">
@@ -469,15 +465,10 @@
       </ReturnValue>
       <MemberValue>13</MemberValue>
       <Docs>
-        <summary>A pointer to an <see langword="IUnknown" /> interface (DBTYPE_UNKNOWN). This maps to <see cref="T:System.Object" />.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This data type is not currently supported by ADO.NET. Usage may cause unpredictable results.  
-  
- ]]></format>
-        </remarks>
+        <summary>A pointer to an <see langword="IUnknown" /> interface (DBTYPE_UNKNOWN). This maps to <see cref="T:System.Object" />.         
+This data type is not currently supported by ADO.NET. Its usage may cause unpredictable results.        
+        </summary>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="LongVarBinary">
diff --git a/xml/System.Data.OracleClient/OracleType.xml b/xml/System.Data.OracleClient/OracleType.xml
@@ -324,15 +324,11 @@
       </ReturnValue>
       <MemberValue>9</MemberValue>
       <Docs>
-        <summary>An Oracle <see langword="LONGRAW" /> data type that contains variable-length binary data with a maximum size of 2 gigabytes. Use the .NET Framework <see langword="Byte[]" /> or OracleClient <see cref="T:System.Data.OracleClient.OracleBinary" /> data type in <see cref="P:System.Data.OracleClient.OracleParameter.Value" />.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- When you update a column with the `LONG RAW` data type, an exception is thrown when you enter a value of `NULL` in the column. The Oracle `LONG RAW` data type is a deprecated type in Oracle version 8.0. To avoid this error, use the `BLOB` data type instead of `LONG RAW`.  
-  
- ]]></format>
-        </remarks>
+        <summary>An Oracle <see langword="LONGRAW" /> data type that contains variable-length binary data with a maximum size of 2 gigabytes. Use the .NET Framework <see langword="Byte[]" /> or OracleClient <see cref="T:System.Data.OracleClient.OracleBinary" /> data type in <see cref="P:System.Data.OracleClient.OracleParameter.Value" />.
+
+ When you update a column with the <c>LONG RAW</c> data type, an exception is thrown when you enter a value of <c>NULL</c> in the column. The Oracle <c>LONG RAW</c> data type is a deprecated type in Oracle version 8.0. To avoid this error, use the <c>BLOB</c> data type instead of <c>LONG RAW</c>.  
+        </summary>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="LongVarChar">
diff --git a/xml/System.Data/CommandBehavior.xml b/xml/System.Data/CommandBehavior.xml
@@ -38,15 +38,21 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
- The <xref:System.Data.CommandBehavior> values are used by the <xref:System.Data.IDbCommand.ExecuteReader%2A> method of <xref:System.Data.IDbCommand> and any classes derived from it.  
+ The `CommandBehavior` values are used by the <xref:System.Data.IDbCommand.ExecuteReader%2A> method of <xref:System.Data.IDbCommand> and any implementing classes.  
   
  A bitwise combination of these values may be used.  
   
- <xref:System.Data.CommandBehavior> is ignored when used to define a <xref:System.Data.Sql.SqlNotificationRequest> or <xref:System.Data.SqlClient.SqlDependency> and should therefore not be used. Use the constructor that does not require a `CommandBehavior` parameter in these two cases.  
-  
+`CommandBehavior` is ignored when used to define a <xref:System.Data.Sql.SqlNotificationRequest> or <xref:System.Data.SqlClient.SqlDependency> and should therefore not be used. Use the constructor that does not require a `CommandBehavior` parameter in these two cases.  
+
+### Notes on individual enumeration members
+
+When using `KeyInfo`, the .NET Framework Data Provider for SQL Server precedes the statement being executed with `SET FMTONLY OFF` and `SET NO_BROWSETABLE ON`. The user should be aware of potential side effects, such as interference with the use of `SET FMTONLY ON` statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql).
+
 > [!NOTE]
->  Use SequentialAccess to retrieve large values and binary data. Otherwise, an <xref:System.OutOfMemoryException> might occur and the connection will be closed.  
-  
+>  Use `SequentialAccess` to retrieve large values and binary data. Otherwise, an <xref:System.OutOfMemoryException> might occur and the connection will be closed.  
+
+When you specify `SequentialAccess`, you are required to read from the columns in the order they are returned, although you are not required to read each column. Once you have read past a location in the returned stream of data, data at or before that location can no longer be read from the `DataReader`. When using the <xref:System.Data.OleDb.OleDbDataReader>, you can reread the current column value until reading past it. When using the <xref:System.Data.SqlClient.SqlDataReader>, you can read a column value only once.  
+
  ]]></format>
     </remarks>
   </Docs>
@@ -153,17 +159,8 @@
       </ReturnValue>
       <MemberValue>4</MemberValue>
       <Docs>
-        <summary>The query returns column and primary key information.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- When KeyInfo is used for command execution, the provider will append extra columns to the result set for existing primary key and timestamp columns.  
-  
- When using KeyInfo, the .NET Framework Data Provider for SQL Server precedes the statement being executed with SET FMTONLY OFF and SET NO_BROWSETABLE ON. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql).
-  
- ]]></format>
-        </remarks>
+        <summary>The query returns column and primary key information. The provider appends extra columns to the result set for existing primary key and timestamp columns.</summary>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="SchemaOnly">
@@ -234,14 +231,7 @@
       <MemberValue>16</MemberValue>
       <Docs>
         <summary>Provides a way for the <see langword="DataReader" /> to handle rows that contain columns with large binary values. Rather than loading the entire row, <see langword="SequentialAccess" /> enables the <see langword="DataReader" /> to load data as a stream. You can then use the <see langword="GetBytes" /> or <see langword="GetChars" /> method to specify a byte location to start the read operation, and a limited buffer size for the data being returned.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- When you specify `SequentialAccess`, you are required to read from the columns in the order they are returned, although you are not required to read each column. Once you have read past a location in the returned stream of data, data at or before that location can no longer be read from the `DataReader`. When using the <xref:System.Data.OleDb.OleDbDataReader>, you can reread the current column value until reading past it. When using the <xref:System.Data.SqlClient.SqlDataReader>, you can read a column value only once.  
-  
- ]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="SingleResult">
diff --git a/xml/System.Data/IsolationLevel.xml b/xml/System.Data/IsolationLevel.xml
@@ -37,13 +37,14 @@
     <remarks>
       <format type="text/markdown"><![CDATA[  
   
-## Remarks  
- The <xref:System.Data.IsolationLevel> values are used by a .NET Framework data provider when performing a transaction.  
-  
- The <xref:System.Data.IsolationLevel> remains in effect until explicitly changed, but it can be changed at any time. The new value is used at execution time, not parse time. If changed during a transaction, the expected behavior of the server is to apply the new locking level to all statements remaining.  
-  
-   
-  
+## Remarks
+
+The `IsolationLevel` values are used by a .NET data provider when performing a transaction.
+
+The `IsolationLevel` remains in effect until explicitly changed, but it can be changed at any time. The new value is used at execution time, not parse time. If changed during a transaction, the expected behavior of the server is to apply the new locking level to all statements remaining.  
+  
+When using <xref:System.Data.Odbc.OdbcTransaction>, if you do not set <xref:System.Data.Odbc.OdbcTransaction.IsolationLevel?displayProperty=nameWithType> or you set it to `Unspecified`, the transaction executes according to the isolation level determined by the driver in use.  
+
 ## Examples  
  This application demonstrates how to use <xref:System.Data.IsolationLevel> in <xref:System.Data.Common.DbTransaction>. The sample will demonstrate which of the following behaviors are allowed in the different isolation levels:  
   
@@ -388,15 +389,8 @@
       <MemberValue>-1</MemberValue>
       <Docs>
         <summary>A different isolation level than the one specified is being used, but the level cannot be determined.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- When using <xref:System.Data.Odbc.OdbcTransaction>, if you do not set <xref:System.Data.IsolationLevel> or you set <xref:System.Data.IsolationLevel> to `Unspecified`, the transaction executes according to the isolation level that is determined by the driver that is being used.  
-  
- ]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
diff --git a/xml/System.Data/XmlReadMode.xml b/xml/System.Data/XmlReadMode.xml
diff --git a/xml/System.Device.Location/GeoPositionStatus.xml b/xml/System.Device.Location/GeoPositionStatus.xml
