`about_PSItem` improvements/corrections

[surfingoldelephant]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_psitem

Summary

Various improvements/corrections for about_PSItem, including a meta note about inconsistent $_/$PSItem usage throughout the docs.

Details

• about_PSItem states $_ is an alias of $PSItem, which is technically incorrect. Given $PSItem came after $_, arguably it's the other way around. Perhaps replace "alias" with a different term to avoid confusion with command aliases.

  lzybkr:

  we introduced $psitem as an alias for $_ because of sufficient feedback that $_ was cryptic and confusing

  BrucePay:

  Very rarely, we try and "fix" things like we did with $_ and $PSItem. This sounded good because new users didn't "get" $_. So we added $PSItem as being easier to understand. The feedback we received from people who teach PowerShell is that rather than helping, having to teach two terms made it worse/more confusing for people trying to learn PowerShell.

• Most public PowerShell content (including the PowerShell Docs) uses $_. Why this is the case ($_ came first) should be explained. I would also emphasise the importance of consistency (i.e., if an existing codebase uses $_, continue to use that).

  • On a meta note: I think it would be worth consolidating $_/$PSItem usage throughout the docs. $_ is typically used, but there's still $PSItem usage spread throughout. One should be picked and used exclusively throughout the repo to avoid unnecessary confusion.
  • I'm happy to submit a PR with this change. Outside of about_PSItem.md, should $_ or $PSItem be used?

• "Dollar underscore", "dollar sign underscore", "variable underscore", etc are all common terms to describe the variable, yet an online search of "PowerShell" and the aforementioned terms doesn't lead to about_PSItem. It might aid discoverability if these terms are included within the doc.

• There's no mention that $_/$PSItem can be assigned to or that doing so may change the behavior of the construct using the variable. Whether or not this is good practice is debatable, but I think it's still worth noting.

  switch ('Foo') {
      Foo { "Hi from $_"; $_ = 'Bar' }
      Bar { "Hi from $_"; $_ = 'Baz'; break }
      Baz { "Hi from $_" }
  }
  
  # Hi from Foo
  # Hi from Bar

• There are a few use cases that can be added to the Long description:

  • In calculated properties
  • In a trap's statement block
  • In the process block of a script block/.ps1 file (this could be combined with function point).

• The term "scriptblock" is incorrectly used when referencing switch and catch. Labelling a statement block as a script block is misleading (e.g., only the latter creates a new scope).

  • switch: "action scriptblocks" is a statement block. Only the conditional is an actual script block.
  • catch: "catch statement ScriptBlock" is also a statement block.