nerdbank-gitversioning 3.4.228 → 3.4.255

package/nbgv.cli/tools/netcoreapp2.1/any/NerdBank.GitVersioning.xml

@@ -2533,6 +2533,11 @@
             Gets the position in a computed version that the version height should appear.
             </summary>
         </member>
+        <member name="P:Nerdbank.GitVersioning.SemanticVersion.GitCommitIdPosition">
+            <summary>
+            Gets the position in a computed version that the first 16 bits of a git commit ID should appear, if any.
+            </summary>
+        </member>
         <member name="P:Nerdbank.GitVersioning.SemanticVersion.IsDefault">
             <summary>
             Gets a value indicating whether this instance is the default "0.0" instance.
@@ -2594,6 +2599,13 @@
             <param name="versionHeightPosition">The position within the version where height is tracked.</param>
             <returns><c>true</c> if transitioning from one version to the next should reset the version height; <c>false</c> otherwise.</returns>
         </member>
+        <member name="M:Nerdbank.GitVersioning.SemanticVersion.IsMatchingVersion(System.Version)">
+            <summary>
+            Checks whether a given version may have been produced by this semantic version.
+            </summary>
+            <param name="version">The version to test.</param>
+            <returns><see langword="true"/> if the <paramref name="version"/> is a match; <see langword="false"/> otherwise.</returns>
+        </member>
         <member name="M:Nerdbank.GitVersioning.SemanticVersion.Contains(System.Version)">
             <summary>
             Checks whether a particular version number
@@ -3214,7 +3226,7 @@
         </member>
         <member name="P:Nerdbank.GitVersioning.VersionOptions.AssemblyVersionOptions.Version">
             <summary>
-            Gets or sets the major.minor components of the assembly version.
+            Gets or sets the components of the assembly version (2-4 components).
             </summary>
         </member>
         <member name="P:Nerdbank.GitVersioning.VersionOptions.AssemblyVersionOptions.Precision">
@@ -4017,7 +4029,7 @@
         <member name="T:Windows.Win32.System.SystemServices.SECURITY_ATTRIBUTES">
             <summary>The SECURITY_ATTRIBUTES structure contains the security descriptor for an object and specifies whether the handle retrieved by specifying this structure is inheritable.</summary>
             <remarks>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//wtypesbase/ns-wtypesbase-security_attributes#">Read more on docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//wtypesbase/ns-wtypesbase-security_attributes#">Read more on docs.microsoft.com</see>.</para>
             </remarks>
         </member>
         <member name="F:Windows.Win32.System.SystemServices.SECURITY_ATTRIBUTES.nLength">
@@ -4026,7 +4038,7 @@
         <member name="F:Windows.Win32.System.SystemServices.SECURITY_ATTRIBUTES.lpSecurityDescriptor">
             <summary>
             <para>A pointer to a [**SECURITY\_DESCRIPTOR**](../winnt/ns-winnt-security_descriptor.md) structure that controls access to the object. If the value of this member is **NULL**, the object is assigned the default security descriptor associated with the [*access token*](/windows/win32/secauthz/access-tokens) of the calling process. This is not the same as granting access to everyone by assigning a **NULL** [*discretionary access control list*](/windows/win32/secauthz/dacls-and-aces) (DACL). By default, the default DACL in the access token of a process allows access only to the user represented by the access token. For information about creating a security descriptor, see [Creating a Security Descriptor](/windows/win32/secauthz/creating-a-security-descriptor-for-a-new-object-in-c--).</para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//wtypesbase/ns-wtypesbase-security_attributes#members">Read more on docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//wtypesbase/ns-wtypesbase-security_attributes#members">Read more on docs.microsoft.com</see>.</para>
             </summary>
         </member>
         <member name="F:Windows.Win32.System.SystemServices.SECURITY_ATTRIBUTES.bInheritHandle">
@@ -4049,9 +4061,9 @@
         </member>
         <member name="M:Windows.Win32.System.SystemServices.PCWSTR.ToString">
             <summary>
-            Returns a <see langword = "string"/> with a copy of this character array.
+            Returns a <see langword="string"/> with a copy of this character array.
             </summary>
-            <returns>A <see langword = "string"/>, or <see langword = "null"/> if <see cref = "F:Windows.Win32.System.SystemServices.PCWSTR.Value"/> is <see langword = "null"/>.</returns>
+            <returns>A <see langword="string"/>, or <see langword="null"/> if <see cref = "F:Windows.Win32.System.SystemServices.PCWSTR.Value"/> is <see langword="null"/>.</returns>
         </member>
         <member name="M:Windows.Win32.System.SystemServices.PCWSTR.AsSpan">
             <summary>
@@ -4068,11 +4080,11 @@
             <param name = "hObject">A valid handle to an open object.</param>
             <returns>
             <para>If the function succeeds, the return value is nonzero.</para>
-            <para>If the function fails, the return value is zero. To get extended error information, call <a href = "/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror">GetLastError</a>.</para>
-            <para>If the application is running under a debugger,  the function will throw an exception if it receives either a  handle value that is not valid  or a pseudo-handle value. This can happen if you close a handle twice, or if you  call <b>CloseHandle</b> on a handle returned by the <a href = "/windows/desktop/api/fileapi/nf-fileapi-findfirstfilea">FindFirstFile</a> function instead of calling the <a href = "/windows/desktop/api/fileapi/nf-fileapi-findclose">FindClose</a> function.</para>
+            <para>If the function fails, the return value is zero. To get extended error information, call <a href="/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror">GetLastError</a>.</para>
+            <para>If the application is running under a debugger,  the function will throw an exception if it receives either a  handle value that is not valid  or a pseudo-handle value. This can happen if you close a handle twice, or if you  call <b>CloseHandle</b> on a handle returned by the <a href="/windows/desktop/api/fileapi/nf-fileapi-findfirstfilea">FindFirstFile</a> function instead of calling the <a href="/windows/desktop/api/fileapi/nf-fileapi-findclose">FindClose</a> function.</para>
             </returns>
             <remarks>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//handleapi/nf-handleapi-closehandle">Learn more about this API from docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//handleapi/nf-handleapi-closehandle">Learn more about this API from docs.microsoft.com</see>.</para>
             </remarks>
         </member>
         <member name="M:Windows.Win32.PInvoke.CreateFile(System.String,Windows.Win32.Storage.FileSystem.FILE_ACCESS_FLAGS,Windows.Win32.Storage.FileSystem.FILE_SHARE_MODE,System.Nullable{Windows.Win32.System.SystemServices.SECURITY_ATTRIBUTES},Windows.Win32.Storage.FileSystem.FILE_CREATION_DISPOSITION,Windows.Win32.Storage.FileSystem.FILE_FLAGS_AND_ATTRIBUTES,System.Runtime.InteropServices.SafeHandle)">
@@ -4082,67 +4094,67 @@
             <summary>Creates or opens a file or I/O device. The most commonly used I/O devices are as follows:\_file, file stream, directory, physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe.</summary>
             <param name = "lpFileName">
             <para>The name of the file or device to be created or opened. You may use either forward slashes (/) or backslashes (\\) in this name.</para>
-            <para>In the ANSI version of this function, the name is limited to <b>MAX_PATH</b> characters. To extend this limit to 32,767 wide characters, use this Unicode version of the function and prepend "\\\\?\\" to the path. For more information, see <a href = "https://docs.microsoft.com/windows/desktop/FileIO/naming-a-file">Naming Files, Paths, and Namespaces</a>.</para>
-            <para>For information on special device names, see <a href = "https://docs.microsoft.com/windows/desktop/FileIO/defining-an-ms-dos-device-name">Defining an MS-DOS Device Name</a>.</para>
-            <para>To create a file stream, specify the name of the file, a colon, and then the name of the stream. For more information, see <a href = "https://docs.microsoft.com/windows/desktop/FileIO/file-streams">File Streams</a>.</para>
-            <para><div class = "alert"><b>Tip</b>  Starting with Windows 10, version 1607, for the unicode version of this function (<b>CreateFileW</b>), you can opt-in to remove the <b>MAX_PATH</b> limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of <a href = "https://docs.microsoft.com/windows/desktop/FileIO/naming-a-file">Naming Files, Paths, and Namespaces</a> for details.</div> <div> </div></para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
+            <para>In the ANSI version of this function, the name is limited to <b>MAX_PATH</b> characters. To extend this limit to 32,767 wide characters, use this Unicode version of the function and prepend "\\\\?\\" to the path. For more information, see <a href="https://docs.microsoft.com/windows/desktop/FileIO/naming-a-file">Naming Files, Paths, and Namespaces</a>.</para>
+            <para>For information on special device names, see <a href="https://docs.microsoft.com/windows/desktop/FileIO/defining-an-ms-dos-device-name">Defining an MS-DOS Device Name</a>.</para>
+            <para>To create a file stream, specify the name of the file, a colon, and then the name of the stream. For more information, see <a href="https://docs.microsoft.com/windows/desktop/FileIO/file-streams">File Streams</a>.</para>
+            <para><div class="alert"><b>Tip</b>  Starting with Windows 10, version 1607, for the unicode version of this function (<b>CreateFileW</b>), you can opt-in to remove the <b>MAX_PATH</b> limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of <a href="https://docs.microsoft.com/windows/desktop/FileIO/naming-a-file">Naming Files, Paths, and Namespaces</a> for details.</div> <div> </div></para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
             </param>
             <param name = "dwDesiredAccess">
             <para>The requested access to the file or device, which can be summarized as read, write, both or neither zero).</para>
-            <para>The most commonly used values are <b>GENERIC_READ</b>, <b>GENERIC_WRITE</b>, or both (<c>GENERIC_READ | GENERIC_WRITE</c>). For more information, see <a href = "https://docs.microsoft.com/windows/desktop/SecAuthZ/generic-access-rights">Generic Access Rights</a>, <a href = "https://docs.microsoft.com/windows/desktop/FileIO/file-security-and-access-rights">File Security and Access Rights</a>, <a href = "https://docs.microsoft.com/windows/desktop/FileIO/file-access-rights-constants">File Access Rights Constants</a>, and <a href = "https://docs.microsoft.com/windows/desktop/SecAuthZ/access-mask">ACCESS_MASK</a>.</para>
+            <para>The most commonly used values are <b>GENERIC_READ</b>, <b>GENERIC_WRITE</b>, or both (<c>GENERIC_READ | GENERIC_WRITE</c>). For more information, see <a href="https://docs.microsoft.com/windows/desktop/SecAuthZ/generic-access-rights">Generic Access Rights</a>, <a href="https://docs.microsoft.com/windows/desktop/FileIO/file-security-and-access-rights">File Security and Access Rights</a>, <a href="https://docs.microsoft.com/windows/desktop/FileIO/file-access-rights-constants">File Access Rights Constants</a>, and <a href="https://docs.microsoft.com/windows/desktop/SecAuthZ/access-mask">ACCESS_MASK</a>.</para>
             <para>If this parameter is zero, the application can query certain metadata such as file, directory, or device attributes without accessing that file or device, even if <b>GENERIC_READ</b> access would have been denied.</para>
             <para>You cannot request an access mode that conflicts with the sharing mode that is specified by the <i>dwShareMode</i> parameter in an open request that already has an open handle.</para>
-            <para>For more information, see the Remarks section of this topic and <a href = "https://docs.microsoft.com/windows/desktop/FileIO/creating-and-opening-files">Creating and Opening Files</a>.</para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
+            <para>For more information, see the Remarks section of this topic and <a href="https://docs.microsoft.com/windows/desktop/FileIO/creating-and-opening-files">Creating and Opening Files</a>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
             </param>
             <param name = "dwShareMode">
             <para>The requested sharing mode of the file or device, which can be read, write, both, delete, all of these, or none (refer to the following table). Access requests to attributes or extended attributes are not affected by this flag.</para>
             <para>If this parameter is zero and <b>CreateFile</b> succeeds, the file or device cannot be shared and cannot be opened again until the handle to the file or device is closed. For more information, see the Remarks section.</para>
-            <para>You cannot request a sharing mode that conflicts with the access mode that is specified in an existing request that has an open handle. <b>CreateFile</b> would fail and the <a href = "https://docs.microsoft.com/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror">GetLastError</a> function would return <b>ERROR_SHARING_VIOLATION</b>.</para>
+            <para>You cannot request a sharing mode that conflicts with the access mode that is specified in an existing request that has an open handle. <b>CreateFile</b> would fail and the <a href="https://docs.microsoft.com/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror">GetLastError</a> function would return <b>ERROR_SHARING_VIOLATION</b>.</para>
             <para>To enable a process to share a file or device while another process has the file or device open, use a</para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
             </param>
             <param name = "lpSecurityAttributes">
-            <para>A pointer to a <a href = "https://docs.microsoft.com/previous-versions/windows/desktop/legacy/aa379560(v=vs.85)">SECURITY_ATTRIBUTES</a> structure that contains two separate but related data members: an optional security descriptor, and a Boolean value that determines whether the returned handle can be inherited by child processes.</para>
+            <para>A pointer to a <a href="https://docs.microsoft.com/previous-versions/windows/desktop/legacy/aa379560(v=vs.85)">SECURITY_ATTRIBUTES</a> structure that contains two separate but related data members: an optional security descriptor, and a Boolean value that determines whether the returned handle can be inherited by child processes.</para>
             <para>This parameter can be <b>NULL</b>.</para>
             <para>If this parameter is <b>NULL</b>, the handle returned by <b>CreateFile</b> cannot be inherited by any child processes the application may create and the file or device associated with the returned handle gets a default security descriptor.</para>
-            <para>The <b>lpSecurityDescriptor</b> member of the structure specifies a <a href = "https://docs.microsoft.com/windows/desktop/api/winnt/ns-winnt-security_descriptor">SECURITY_DESCRIPTOR</a> for a file or device. If this member is <b>NULL</b>, the file or device associated with the returned handle is assigned a default security descriptor.</para>
+            <para>The <b>lpSecurityDescriptor</b> member of the structure specifies a <a href="https://docs.microsoft.com/windows/desktop/api/winnt/ns-winnt-security_descriptor">SECURITY_DESCRIPTOR</a> for a file or device. If this member is <b>NULL</b>, the file or device associated with the returned handle is assigned a default security descriptor.</para>
             <para><b>CreateFile</b> ignores the <b>lpSecurityDescriptor</b> member when opening an existing file or device, but continues to use the <b>bInheritHandle</b> member.</para>
             <para>The <b>bInheritHandle</b>member of the structure specifies whether the returned handle can be inherited.</para>
             <para>For more information, see the Remarks section.</para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
             </param>
             <param name = "dwCreationDisposition">
             <para>An action to take on a file or device that exists or does not exist.</para>
             <para>For devices other than files, this parameter is usually set to <b>OPEN_EXISTING</b>.</para>
             <para>For more information, see the Remarks section.</para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
             </param>
             <param name = "dwFlagsAndAttributes">
-            <para>The file or device attributes and flags, <b>FILE_ATTRIBUTE_NORMAL</b> being the most common default value for files. This parameter can include any combination of the available file attributes (<b>FILE_ATTRIBUTE_*</b>). All other file attributes override <b>FILE_ATTRIBUTE_NORMAL</b>. This parameter can also contain combinations of flags (<b>FILE_FLAG_*</b>) for control of file or device caching behavior, access modes, and other special-purpose flags. These combine with any <b>FILE_ATTRIBUTE_*</b> values. This parameter can also contain Security Quality of Service (SQOS) information by specifying the <b>SECURITY_SQOS_PRESENT</b> flag. Additional SQOS-related flags information is presented in the table following the attributes and flags tables. <div class = "alert"><b>Note</b>  When <b>CreateFile</b> opens an existing file, it generally combines the file flags with the file attributes of the existing file, and ignores any file attributes supplied as part of <i>dwFlagsAndAttributes</i>. Special cases are detailed in <a href = "https://docs.microsoft.com/windows/desktop/FileIO/creating-and-opening-files">Creating and Opening Files</a>.</div> <div> </div> Some of the following file attributes and flags may only apply to files and not necessarily all other types of devices that <b>CreateFile</b> can open. For additional information, see the Remarks section of this topic and <a href = "https://docs.microsoft.com/windows/desktop/FileIO/creating-and-opening-files">Creating and Opening Files</a>. For more advanced access to file attributes, see <a href = "https://docs.microsoft.com/windows/desktop/api/fileapi/nf-fileapi-setfileattributesa">SetFileAttributes</a>. For a complete list of all file attributes with their values and descriptions, see <a href = "https://docs.microsoft.com/windows/desktop/FileIO/file-attribute-constants">File Attribute Constants</a>. </para>
+            <para>The file or device attributes and flags, <b>FILE_ATTRIBUTE_NORMAL</b> being the most common default value for files. This parameter can include any combination of the available file attributes (<b>FILE_ATTRIBUTE_*</b>). All other file attributes override <b>FILE_ATTRIBUTE_NORMAL</b>. This parameter can also contain combinations of flags (<b>FILE_FLAG_*</b>) for control of file or device caching behavior, access modes, and other special-purpose flags. These combine with any <b>FILE_ATTRIBUTE_*</b> values. This parameter can also contain Security Quality of Service (SQOS) information by specifying the <b>SECURITY_SQOS_PRESENT</b> flag. Additional SQOS-related flags information is presented in the table following the attributes and flags tables. <div class="alert"><b>Note</b>  When <b>CreateFile</b> opens an existing file, it generally combines the file flags with the file attributes of the existing file, and ignores any file attributes supplied as part of <i>dwFlagsAndAttributes</i>. Special cases are detailed in <a href="https://docs.microsoft.com/windows/desktop/FileIO/creating-and-opening-files">Creating and Opening Files</a>.</div> <div> </div> Some of the following file attributes and flags may only apply to files and not necessarily all other types of devices that <b>CreateFile</b> can open. For additional information, see the Remarks section of this topic and <a href="https://docs.microsoft.com/windows/desktop/FileIO/creating-and-opening-files">Creating and Opening Files</a>. For more advanced access to file attributes, see <a href="https://docs.microsoft.com/windows/desktop/api/fileapi/nf-fileapi-setfileattributesa">SetFileAttributes</a>. For a complete list of all file attributes with their values and descriptions, see <a href="https://docs.microsoft.com/windows/desktop/FileIO/file-attribute-constants">File Attribute Constants</a>. </para>
             <para>This doc was truncated.</para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
             </param>
             <param name = "hTemplateFile">
             <para>A valid handle to a template file with the <b>GENERIC_READ</b> access right. The template file supplies file attributes and extended attributes for the file that is being created.</para>
             <para>This parameter can be <b>NULL</b>.</para>
             <para>When opening an existing file, <b>CreateFile</b> ignores this parameter.</para>
-            <para>When opening a new encrypted file, the file inherits the discretionary access control list from its parent directory. For additional information, see <a href = "https://docs.microsoft.com/windows/desktop/FileIO/file-encryption">File Encryption</a>.</para>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
+            <para>When opening a new encrypted file, the file inherits the discretionary access control list from its parent directory. For additional information, see <a href="https://docs.microsoft.com/windows/desktop/FileIO/file-encryption">File Encryption</a>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew#parameters">Read more on docs.microsoft.com</see>.</para>
             </param>
             <returns>
             <para>If the function succeeds, the return value is an open handle to the specified file, device, named pipe, or mail slot.</para>
-            <para>If the function fails, the return value is <b>INVALID_HANDLE_VALUE</b>. To get extended error information, call <a href = "/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror">GetLastError</a>.</para>
+            <para>If the function fails, the return value is <b>INVALID_HANDLE_VALUE</b>. To get extended error information, call <a href="/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror">GetLastError</a>.</para>
             </returns>
             <remarks>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew">Learn more about this API from docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//fileapi/nf-fileapi-createfilew">Learn more about this API from docs.microsoft.com</see>.</para>
             </remarks>
         </member>
         <member name="F:Windows.Win32.Constants.INVALID_HANDLE_VALUE">
             <summary>There is no interactive user. The trust provider performs the verification action without the user's assistance.</summary>
             <remarks>
-            <para><see href = "https://docs.microsoft.com/windows/win32/api//wintrust/nf-wintrust-winverifytrustex">Learn more about this API from docs.microsoft.com</see>.</para>
+            <para><see href="https://docs.microsoft.com/windows/win32/api//wintrust/nf-wintrust-winverifytrustex">Learn more about this API from docs.microsoft.com</see>.</para>
             </remarks>
         </member>
     </members>