Consider changing the term "empty null" to "enumerable null" or "null enumerable"

mklement0 commented 3 weeks ago

Type of issue

Other (describe below)

Feedback

Suggested terminology change:

[System.Management.Automation.Internal.AutomationNull]::Value behaves like an enumerable in enumeration contexts.
In expression contexts, it behaves like $null

Arguably, either value is "empty", so using "empty null" to describe the former doesn't serve to distinguish these values.

I therefore suggest calling [System.Management.Automation.Internal.AutomationNull]::Value the enumerable null or null enumerable (see discussion below).

Page URL

https://learn.microsoft.com/en-us/powershell/scripting/learn/deep-dives/everything-about-null?view=powershell-7.4#empty-null

Content source URL

https://github.com/MicrosoftDocs/PowerShell-Docs/blob/main/reference/docs-conceptual/learn/deep-dives/everything-about-null.md

Author

@sdwheeler

Document Id

53e31d8c-92e1-d484-f9d4-b79ded54c1d1

iSazonov commented 3 weeks ago

I therefore suggest calling [System.Management.Automation.Internal.AutomationNull]::Value the enumerable null.

It can still confuse. Maybe replace null with AutomationNull as doc term.

mklement0 commented 3 weeks ago

@iSazonov:

It is hard to come up with a descriptive yet pithy term. The essence of [System.Management.Automation.Internal.AutomationNull]::Value is: it is a $null that is also an enumerable; if it is enumerated, it enumerates nothing.

An alternative would be "null enumerable".

The only reason to pick "AutomationNull" would be to align with the underlying type name, which in itself isn't descriptive either.

At the end of the day, "AutomationNull" is preferable to "empty null", but given the pending change to create a fully public type - see https://github.com/PowerShell/PowerShell/issues/13465#issuecomment-1377486490 - this could be an opportunity to rename the type too; e.g., the implementation could be, based on https://github.com/PowerShell/PowerShell/issues/9997#issuecomment-580743572:

namespace System.Management.Automation
{
    // New, fully public class
    public sealed class NullEnumerable : PSObject
    {
        private NullEnumerable()
        {
        }

        public static NullEnumerable Value { get; } = new NullEnumerable();
    }
}

namespace System.Management.Automation.Internal
{
    // Original, "pubternal" class
    [Obsolete("Use System.Management.Automation.AutomationNull")]
    public static class AutomationNull
    {
        public static PSObject Value => System.Management.Automation.NullEnumerable.Value;
    }
}

MicrosoftDocs / PowerShell-Docs