Missing API docs part 1 - SA (#3531)

* missing API docs part 1

* escape characters

* review changes

Author: steveada

xml/Microsoft.Build.Tasks/GenerateManifestBase.xml

@@ -289,11 +289,12 @@
         <Parameter Name="versionB" Type="System.String" Index="1" FrameworkAlternate="netframework-3.5" />
       </Parameters>
       <Docs>
-        <param name="versionA">To be added.</param>
-        <param name="versionB">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="versionA">The first .NET Framework version to compare.</param>
+        <param name="versionB">The second .NET Framework version to compare.</param>
+        <summary>Compares two .NET Framework versions and determines which version comes before the other one.</summary>
+        <returns>An integer value that specifies the sort order position of a .NET Framework version instance relative to another version instance. A value of 0 means the two values are equal, a value of -1 indicates that <paramref name="versionA" /> precedes <paramref name="versionB" />, and a value of 1 indicates that <paramref name="versionA" /> comes after <paramref name="versionB" />.</returns>
         <remarks>To be added.</remarks>
+        <forInternalUseOnly />
       </Docs>
     </Member>
     <Member MemberName="ConvertFrameworkVersionToString">
@@ -314,10 +315,11 @@
         <Parameter Name="version" Type="System.String" Index="0" FrameworkAlternate="netframework-3.5" />
       </Parameters>
       <Docs>
-        <param name="version">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="version">The .NET Framework version number to convert to a string.</param>
+        <summary>Converts the given .NET Framework version to a string.</summary>
+        <returns>A string that represents the .NET Framework version.</returns>
         <remarks>To be added.</remarks>
+        <forInternalUseOnly />
       </Docs>
     </Member>
     <Member MemberName="Description">

xml/Microsoft.CSharp.Activities/CSharpReference`1.xml

@@ -32,7 +32,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <typeparam name="TResult">To be added.</typeparam>
+    <typeparam name="TResult">The type of the C# reference.</typeparam>
     <summary>Specifies information about a C# reference.</summary>
     <remarks>To be added.</remarks>
   </Docs>

xml/Microsoft.CSharp/ErrorLevel.xml

@@ -41,7 +41,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>An error diagnostic.</summary>
       </Docs>
     </Member>
     <Member MemberName="FatalError">
@@ -62,7 +62,7 @@
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>A noncontinuable error diagnostic.</summary>
       </Docs>
     </Member>
     <Member MemberName="None">
@@ -83,7 +83,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>An unknown severity.</summary>
       </Docs>
     </Member>
     <Member MemberName="Warning">
@@ -104,7 +104,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>A warning or suggestive diagnostic.</summary>
       </Docs>
     </Member>
   </Members>

xml/Microsoft.IE/Manager+URL_CANONFLAGS.xml

@@ -44,7 +44,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>33554432</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Defined to be the same as URL_DONT_ESCAPE_EXTRA_INFO.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_CONVERT_IF_DOSPATH">
@@ -65,7 +65,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>2097152</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Convert to a URL if in a dospath format.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_DONT_ESCAPE_EXTRA_INFO">
@@ -86,7 +86,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>33554432</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Used only in conjunction with URL_ESCAPE_SPACES_ONLY to prevent the conversion of characters in the query (the portion of the URL following the first # or ? character encountered in the string). This flag should not be used alone or combined with URL_ESCAPE_SEGMENT_ONLY.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_DONT_SIMPLIFY">
@@ -107,7 +107,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>134217728</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Treat "/./" and "/../" in a URL string as literal characters, not as shorthand for navigation.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_DONT_UNESCAPE_EXTRA_INFO">
@@ -128,7 +128,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>33554432</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Used only in conjunction with URL_ESCAPE_SPACES_ONLY to prevent the conversion of characters in the query (the portion of the URL following the first # or ? character encountered in the string). This flag should not be used alone or combined with URL_ESCAPE_SEGMENT_ONLY.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_ESCAPE_PERCENT">
@@ -149,7 +149,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>4096</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Convert any occurrence of "%" to its escape sequence.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_ESCAPE_SEGMENT_ONLY">
@@ -170,7 +170,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>8192</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Indication that the URL contains only the section following the server component but preceding the query. All unsafe characters in the string are converted. If a full URL is provided when this flag is set, all unsafe characters in the entire string are converted, including # and ? characters. Combine this flag with URL_ESCAPE_PERCENT to include that character in the conversion. This flag cannot be combined with URL_ESCAPE_SPACES_ONLY or URL_DONT_ESCAPE_EXTRA_INFO.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_ESCAPE_SPACES_ONLY">
@@ -191,7 +191,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>67108864</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Replace only spaces with escape sequences. This flag takes precedence over URL_ESCAPE_UNSAFE, but does not apply to opaque URLs.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_ESCAPE_UNSAFE">
@@ -212,7 +212,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>536870912</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Replace unsafe characters with their escape sequences. Unsafe characters are those characters that may be altered during transport across the Internet, and include the &lt;, &gt;, &quot;, #, {, }, |, \, ^, [, ], and &apos; characters. This flag applies to all URLs, including opaque URLs.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_FILE_USE_PATHURL">
@@ -233,7 +233,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>65536</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Use DOS path compatibility mode to create "file" Uniform Resource Identifiers (URIs).</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_INTERNAL_PATH">
@@ -254,7 +254,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>8388608</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Convert any occurrence of "#" to its escape sequence.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_NO_META">
@@ -275,7 +275,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>134217728</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Defined to be the same as URL_DONT_SIMPLIFY.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_PLUGGABLE_PROTOCOL">
@@ -296,7 +296,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>1073741824</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Combine URLs with client-defined pluggable protocols, according to the World Wide Web Consortium (W3C) specification. This flag does not apply to standard protocols such as ftp, http, gopher, and so on.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_UNESCAPE">
@@ -317,7 +317,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>268435456</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Unescape any escape sequences that the URLs contain, with two exceptions. The escape sequences for "?" and "#" are not un-escaped. If one of the URL_ESCAPE flags is also set, the two URLs are first un-escaped, then combined, then escaped.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_UNESCAPE_HIGH_ANSI_ONLY">
@@ -338,7 +338,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>4194304</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Unescape only high ANSI escape characters.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_UNESCAPE_INPLACE">
@@ -359,7 +359,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>1048576</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Convert escape sequences back into ordinary characters and overwrites the original string.</summary>
       </Docs>
     </Member>
     <Member MemberName="URL_WININET_COMPATIBILITY">
@@ -380,7 +380,7 @@ This enumeration is used in calls to the unmanaged Windows function UrlCanonical
       </ReturnValue>
       <MemberValue>-2147483648</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Merge all the parameters to create a full URL.</summary>
       </Docs>
     </Member>
   </Members>

xml/Microsoft.IE/Manager+URL_IS.xml

@@ -44,7 +44,7 @@ This enumeration is used in calls to the unmanaged UrlIs function.
       </ReturnValue>
       <MemberValue>4</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The UrlIs function will attempt to determine a valid scheme for the URL.</summary>
       </Docs>
     </Member>
     <Member MemberName="URLIS_DIRECTORY">
@@ -65,7 +65,7 @@ This enumeration is used in calls to the unmanaged UrlIs function.
       </ReturnValue>
       <MemberValue>5</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The URL string ends with a directory name.</summary>
       </Docs>
     </Member>
     <Member MemberName="URLIS_FILEURL">
@@ -86,7 +86,7 @@ This enumeration is used in calls to the unmanaged UrlIs function.
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The URL is a file URL, which takes the form file://host/path.</summary>
       </Docs>
     </Member>
     <Member MemberName="URLIS_HASQUERY">
@@ -107,7 +107,7 @@ This enumeration is used in calls to the unmanaged UrlIs function.
       </ReturnValue>
       <MemberValue>6</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The URL has an appended query string.</summary>
       </Docs>
     </Member>
     <Member MemberName="URLIS_NOHISTORY">
@@ -128,7 +128,7 @@ This enumeration is used in calls to the unmanaged UrlIs function.
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The URL is a no-history URL, which is a URL that browsers typically do not include in their navigation history.</summary>
       </Docs>
     </Member>
     <Member MemberName="URLIS_OPAQUE">
@@ -149,7 +149,7 @@ This enumeration is used in calls to the unmanaged UrlIs function.
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The URL is opaque, which means that it has a scheme that is not followed by two forward slashes (//).</summary>
       </Docs>
     </Member>
     <Member MemberName="URLIS_URL">
@@ -170,7 +170,7 @@ This enumeration is used in calls to the unmanaged UrlIs function.
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The URL is valid.</summary>
       </Docs>
     </Member>
   </Members>

xml/Microsoft.IE/Manager+URL_PART.xml

@@ -37,7 +37,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The host name part of the URL.</summary>
       </Docs>
     </Member>
     <Member MemberName="NONE">
@@ -58,7 +58,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>No part of the URL.</summary>
       </Docs>
     </Member>
     <Member MemberName="PASSWORD">
@@ -79,7 +79,7 @@
       </ReturnValue>
       <MemberValue>4</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The password part of the URL.</summary>
       </Docs>
     </Member>
     <Member MemberName="PORT">
@@ -100,7 +100,7 @@
       </ReturnValue>
       <MemberValue>5</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The port number part of the URL.</summary>
       </Docs>
     </Member>
     <Member MemberName="QUERY">
@@ -121,7 +121,7 @@
       </ReturnValue>
       <MemberValue>6</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The query string part of the URL.</summary>
       </Docs>
     </Member>
     <Member MemberName="SCHEME">
@@ -142,7 +142,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The URL scheme.</summary>
       </Docs>
     </Member>
     <Member MemberName="USERNAME">
@@ -163,7 +163,7 @@
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The user name part of the URL.</summary>
       </Docs>
     </Member>
   </Members>