(chocolatey#1074) Add documentation for Assert-ValidChecksum

astro.config.mjs

@@ -209,8 +209,8 @@ export default defineConfig({
         '/docs/CreatePackages': '/en-us/create/create-packages/',
         '/docs/helpers-format-file-size': '/en-us/create/functions/format-filesize/',
         '/docs/helpersformatfilesize': '/en-us/create/functions/format-filesize/',
-        '/docs/helpers-get-checksum-valid': '/en-us/create/functions/get-checksumvalid/',
-        '/docs/helpersgetchecksumvalid': '/en-us/create/functions/get-checksumvalid/',
+        '/docs/helpers-get-checksum-valid': '/en-us/create/cmdlets/assert-validchecksum',
+        '/docs/helpersgetchecksumvalid': '/en-us/create/cmdlets/assert-validchecksum',
         '/docs/helpers-get-chocolatey-config-value': '/en-us/create/functions/get-chocolateyconfigvalue/',
         '/docs/helpersgetchocolateyconfigvalue': '/en-us/create/functions/get-chocolateyconfigvalue/',
         '/docs/helpers-get-chocolatey-path': '/en-us/create/functions/get-chocolateypath/',
@@ -347,6 +347,7 @@ export default defineConfig({
         '/docs/roadmap': '/en-us/roadmap/',
         '/docs/troubleshooting': '/en-us/troubleshooting/',
         '/docs/why': '/en-us/why/',
+        '/en-us/create/functions/get-checksumvalid/': '/en-us/create/cmdlets/assert-validchecksum',
         '/en-us/create/functions/get-environmentvariable': '/en-us/create/cmdlets/get-environmentvariable/',
         '/en-us/create/functions/get-environmentvariablenames': '/en-us/create/cmdlets/get-environmentvariablenames/',
         '/en-us/create/functions/install-chocolateypath': '/en-us/create/cmdlets/install-chocolateyPath/',

src/content/docs/en-us/create/cmdlets/Assert-ValidChecksum.mdx

@@ -1,39 +1,56 @@
 ---
+description: Information on Assert-ValidChecksum cmdlet
 external help file: Chocolatey.PowerShell.dll-Help.xml
 Module Name: Chocolatey.PowerShell
-online version:
+online version: https://docs.chocolatey.org/en-us/create/cmdlets/assert-validchecksum
+order: 20
 schema: 2.0.0
+title: Assert-ValidChecksum
+xref: assert-validchecksum
 ---
 import Xref from '@components/Xref.astro';
 
 # Assert-ValidChecksum
 
 ## SYNOPSIS
-{{ Fill in the Synopsis }}
+Checks a file's checksum versus a passed checksum and checksum type.
 
 ## SYNTAX
 
 ```
 Assert-ValidChecksum [-Path] <String> [[-Checksum] <String>] [[-ChecksumType] <ChecksumType>] [[-Url] <String>]
- [-IgnoredArguments <Object[]>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
+ [-IgnoredArguments <Object[]>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
-{{ Fill in the Description }}
+
+Makes a determination if a file meets an expected checksum signature.
+This function is usually used when comparing a file that is downloaded from an official distribution point.
+If the checksum fails to match the expected output, this function throws an error.
+
+Checksums have been used for years as a means of verification. A checksum hash is a unique value or signature that corresponds to the contents of a file.
+File names and extensions can be altered without changing the checksum signature.
+However if you changed the contents of the file, even one character, the checksum will be different.
+
+Checksums are used to provide as a means of cryptographically ensuring the contents of a file have not been changed.
+While some cryptographic algorithms, including MD5 and SHA1, are no longer considered secure against attack, the goal of a checksum algorithm is to make it extremely difficult (near impossible with better algorithms) to alter the contents of a file (whether by accident or for malicious reasons) and still result in the same checksum signature.
+
+When verifying a checksum using a secure algorithm, if the checksum matches the expected signature, the contents of the file are identical to what is expected.
 
 ## EXAMPLES
 
 ### Example 1
 ```powershell
-PS C:\> {{ Add example code here }}
+PS C:\> Assert-ValidChecksum -Path $fileFullPath -Checksum $checksum -ChecksumType $checksumType
 ```
 
-{{ Add example description here }}
+Calculates the `$checksumType` checksum of the file at `$fileFullPath` and compares it to the provided `$checksum` value.
+If the checksums do not match, or the `checksum.exe` is missing, this will throw an error.
 
 ## PARAMETERS
 
 ### -Checksum
-{{ Fill Checksum Description }}
+The checksum value that the file is expected to match.
 
 ```yaml
 Type: String
@@ -48,7 +65,7 @@ Accept wildcard characters: False
 ```
 
 ### -ChecksumType
-{{ Fill ChecksumType Description }}
+The type of checksum algorithm to use.
 
 ```yaml
 Type: ChecksumType
@@ -64,7 +81,7 @@ Accept wildcard characters: False
 ```
 
 ### -IgnoredArguments
-{{ Fill IgnoredArguments Description }}
+Allows splatting with arguments that do not apply. Do not use directly.
 
 ```yaml
 Type: Object[]
@@ -79,7 +96,7 @@ Accept wildcard characters: False
 ```
 
 ### -Path
-{{ Fill Path Description }}
+The path to the file to verify the checksum for.
 
 ```yaml
 Type: String
@@ -94,7 +111,8 @@ Accept wildcard characters: False
 ```
 
 ### -Url
-{{ Fill Url Description }}
+The original URL that the file was downloaded from, if any.
+This is primarily for internal use, and will only matter if certain Chocolatey CLI features are enabled and there is no `-Checksum` value provided.
 
 ```yaml
 Type: String
@@ -108,31 +126,39 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ProgressAction
-{{ Fill ProgressAction Description }}
-
-```yaml
-Type: ActionPreference
-Parameter Sets: (All)
-Aliases: proga
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### CommonParameters
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
-### System.Object[]
-
 ## OUTPUTS
 
-### System.Object
 ## NOTES
+This uses the checksum.exe tool available separately at https://community.chocolatey.org/packages/checksum.
+
+Chocolatey CLI options that affect checksum verification:
+
+- `--ignore-checksums` - skips checksumming
+- `--allow-empty-checksums` - skips checksumming when the package is missing a checksum
+- `--allow-empty-checksums-secure` - skips checksumming when the package is missing a checksum for secure (HTTPS) locations
+- `--require-checksums` - requires checksums for both non-secure and secure locations
+- `--download-checksum`, `--download-checksum-type` - allows user to pass their own checksums
+- `--download-checksum-x64`, `--download-checksum-type-x64` - allows user to pass their own checksums
+
+Chocolatey CLI features that affect checksum verification:
+
+- `checksumFiles` - when turned off, skips checksumming
+- `allowEmptyChecksums` - when turned on, skips checksumming when the package is missing a checksum
+- `allowEmptyChecksumsSecure` - when turned on, skips checksumming when the package is missing a checksum for secure (HTTPS) locations
+
+This command is also aliased to `Get-ChecksumValid` for compatibility with packages designed for Chocolatey CLI v2.x and earlier.
 
 ## RELATED LINKS
+
+<Xref title="Get-ChocolateyWebFile" value="get-chocolateywebfile" classes="mb-3 d-block" />
+
+<Xref title="Install-ChocolateyPackage" value="install-chocolateypackage" classes="mb-3 d-block" />
+
+<Xref title="Cmdlet Reference" value="powershell-cmdlet-reference" classes="mb-3 d-block" />
+
+<Xref title="Function Reference" value="powershell-reference" />

src/content/docs/en-us/create/cmdlets/index.mdx

@@ -21,6 +21,7 @@ Keep in mind Chocolatey's automation scripts are just PowerShell, so you can do
 
 ## Complete List (alphabetical order)
 
+ * <Xref title='Assert-ValidChecksum' value='assert-validchecksum' />
  * <Xref title="Get-EnvironmentVariable" value="get-environmentvariable" />
  * <Xref title="Get-EnvironmentVariableNames" value="get-environmentvariablenames" />
  * <Xref title="Install-ChocolateyPath" value="get-environmentvariable" />

src/content/docs/en-us/create/functions/index.mdx

@@ -64,7 +64,7 @@ These are the functions from above as one list.
 ## Complete List (alphabetical order)
 
  * <Xref title='Format-FileSize' value='format-filesize' />
- * <Xref title='Get-ChecksumValid' value='get-checksumvalid' />
+ * <Xref title='Assert-ValidChecksum' value='assert-validchecksum' />
  * <Xref title='Get-ChocolateyConfigValue' value='get-chocolateyconfigvalue' />
  * <Xref title='Get-ChocolateyPath' value='get-chocolateypath' />
  * <Xref title='Get-ChocolateyUnzip' value='get-chocolateyunzip' />