• The -Raw switch:

  • must be documented as obsolete in v6+, given that it is now a no-op - see Format-Hex -Raw parameter is not documented #1940
  • must have a description added for v5.1 (the version in which it was introduced, also the only version in which it had any functionality) - see https://github.com/PowerShell/PowerShell/pull/3320/files#diff-9d6f8c0ef1420c0a15209f186c5c1f17L227

• -InputObject / pipeline input supports only a limited number of input types, which should be documented:

  • The types are [string], [byte]/[byte[]], [int],[int[]], and [long] / [long[]], as well as [system.io.fileinfo] instances for piping from Get-ChildItem - see https://github.com/PowerShell/PowerShell/blob/master/src/Microsoft.PowerShell.Commands.Utility/commands/utility/FormatAndOutput/format-hex/Format-Hex.cs#L227

  • Any other type causes the following error:
    Cannot convert input of type <type> to hexadecimal. To view the hexadecimal formatting of its string representation, pipe it to the Out-String cmdlet before piping it to Format-Hex."

• The -Encoding parameter:

  • is incorrectly described in general: its true purpose is to control the output encoding whose byte representation to output, and it only applies to input objects received via the pipeline (whereas input read directly from a file is always output as the file's raw byte representation).

    • additionally, it only applies to [string] input; with any of the supported numeric types, -Encoding has no effect.

  • is incorrectly described as defaulting to Unicode; the true defaults are:

    • Windows PowerShell: ASCII; note that that means that non-ASCII characters in the input are output as literal ? chars. (single 0x3F bytes), resulting in a loss of information.

    • PowerShell Core: UTF-8

Additionally, it makes sense to explain the limitations of the right-most column that tries to render the bytes as characters:

• Generally, each byte is interpreted as a Unicode code point, which means that:
  • (printable) ASCII[-range] characters are always printed correctly, as themselves.
  • multi-byte UTF-8 characters never render correctly
  • UTF-16 characters render correctly only if their high byte happens be NUL.

Version(s) of document impacted

• Impacts 6.next document
• Impacts 6 document
• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document

Reason(s) for not selecting all version of documents

• The documented feature was introduced in selected version of PowerShell
• This issue only shows up in selected version of the document