about_Functions_OutputTypeAttribute is misleading

[MartinGC94]

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_functions_outputtypeattribute

Summary

The documentation says:

The OutputType attribute value is only a documentation note.

and nowhere else on the page does it say anything about it being used for type inference/tab completion so developers might think it's an unimportant attribute that they can omit without impacting the user.
It should be highlighted that this is what allows the user to get completion results for situations like: Command | Select <Tab> and Command | Where <Tab>.

In the notes section it also says:

The value of the OutputType property can be null. Use a null value when the output isn't a .NET type, such as a WMI object or a formatted view of an object.

which is bad advice. WMI objects should use a string formatted like: Microsoft.Management.Infrastructure.CimInstance#ROOT/Microsoft/Windows/Storage/MSFT_Disk to indicate which WMI class it outputs from.

For formatted views someone from Microsoft might have to chime in but IMO System.Object would be better to at least indicate that it outputs something to the pipeline, even if you can't specify what it is. In the case of PowerShell scripts/functions this advice is especially important because this allows the type inference code to then try to infer the scriptblock data: https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/parser/TypeInferenceVisitor.cs#L1447

Details

No response

Suggested Fix

No response

[sdwheeler]

@MartinGC94 Thanks for the feedback.