Fixes #8533 - Add doc for using generic methods #8554

sdwheeler · 2022-02-01T21:43:43Z

PR Summary

Fixes AB#1914169 - Fixes #8533 - Add doc for using generic methods

PR Context

Check the boxes below to indicate the content affected by this PR.

Repository or docset configuration

Repo documentation and configuration (.git/.github/.vscode etc.)
Docs build files (.openpublishing.* and build scripts)
Docset configuration (docfx.json, mapping, bread, module folder)

Conceptual documentation

Files in docs-conceptual

Cmdlet reference & about_ topics
When changing cmdlet reference or about_ topics, the changes should be copied to all
relevant versions. Check the boxes below to indicate the versions affected by this change.

PR Checklist

I have read the contributors guide and followed the style and process guidelines
PR has a meaningful title
PR is targeted at the staging branch
All relevant versions updated
Includes content related to issues and PRs - see Closing issues using keywords.
This PR is ready to merge and is not Work in Progress. If the PR is work in progress,
please add the prefix WIP: or [WIP] to the beginning of the title and remove the prefix when
the PR is ready.

opbld31 · 2022-02-01T21:45:57Z

Docs Build status updates of commit 2b7456c:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md	✅Succeeded	View (powershell-7.3)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld33 · 2022-02-01T21:48:10Z

Docs Build status updates of commit 884b074:

❌ Validation status: errors

Please follow instructions here which may help to resolve issue.

File	Status	Preview URL	Details
	❌Error		Details

[Error: RuningBuildFailed] Some unexpected errors happened when running build, please open a ticket in https://aka.ms/SiteHelp and include the error report for our team to troubleshoot

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld33 · 2022-02-01T21:51:33Z

Docs Build status updates of commit 28c84c3:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md	✅Succeeded	View (powershell-7.3)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md

daxian-dbw · 2022-02-01T21:59:11Z

reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md

+[Invoking generic methods on non-generic classes in PowerShell](https://www.leeholmes.com/invoking-generic-methods-on-non-generic-classes-in-powershell/).
+
+A generic method is a method with two parameter lists: a list of generic type parameters and a list
+of formal parameters.


Not necessarily a list of parameters. e.g. Array.Empty<XXX>()

Do you mean, the formal parameter list could be empty? So zero or more parameters.

See my updated version.

Do you mean, the formal parameter list could be empty? So zero or more parameters.

Yes, it could be 0 or more method arguments.

daxian-dbw · 2022-02-01T22:05:40Z

reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md

+        [math]::Pow($item, 3)
+    }
+)
+$result


This example works even without the new generic method feature (see below).
Maybe change it to a code snippet that is enabled by this new feature.

This was one of the pester tests. I tried this in 7.3-preview.1 it does not work.

ParserError: Line | 1 | $result = [System.Linq.Enumerable]::Select[int, float]( | ~ | Array index expression is missing or not valid.

I tested in a current build of master. It works there.

Without the [int, float] part. Please take a closer look at the screenshot above :)
PowerShell is able to infer the generic argument in this case.

OK, I see that now. The example, as written, is enabled by the new feature. But, as you point out, you can remove types and it works. Can anyone provide a better example?

cc: @vexx32

Currently the main things that are strictly enabled by this are methods with zero arguments for PS to infer from, for example:

[System.Linq.Enumerable]::Empty[string]() [array]::Empty[int]()

While it's not yet the case, it could also be used to improve generic method resolution to require less casts (in theory). For example, currently to call [System.Linq.Enumerable]::Select() you have to cast some or all of the arguments to specific types as you have above.

For example, it should be possible to reduce the call above to [System.Linq.Enumerable]::Select[int, float]($list, { <# script block stuff #> }) and avoid the additional casts which are currently necessary.

I think the example as written is fine to illustrate the usage, even if it's not strictly required in all cases currently. Some folks may well just use it to be explicit about exactly what they're calling.

Method resolution can be very complicated, and there can be cases where a method may have both generic and non-generic overloads, where PS could have trouble resolving or may resolve incorrectly (from the user's perspective) without the explicit generic method arguments.

Without a better example, I think this illustrates the point (@vexx32 said).

For example, it should be possible to reduce the call above to [System.Linq.Enumerable]::Select[int, float]($list, { <# script block stuff #> }) and avoid the additional casts which are currently necessary.

This doesn't work for Select, because there is still ambiguity in the type of the delegate as an argument. See the screenshot below:

But it works for IEnumerable.Any -- when specifying the generic type argument ([int] in this case), no need to have explicit cast for the script block.

I'm fine to keep the current example, or use the Any method as an example (it's up to you @sdwheeler). But please add another one for [array]::Empty[int](), because that's the scenario enabled by this new feature, which doesn't work before.

Ok. Will add [Array]::Empty[int]().

opbld30 · 2022-02-02T16:39:16Z

Docs Build status updates of commit 57d5454:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md	✅Succeeded	View (powershell-7.3)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld33 · 2022-02-02T19:34:10Z

Docs Build status updates of commit 1079c4a:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md	✅Succeeded	View (powershell-7.3)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld30 · 2022-02-02T19:36:38Z

Docs Build status updates of commit 4ac49c9:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.3/Microsoft.PowerShell.Core/About/about_Calling_Generic_Methods.md	✅Succeeded	View (powershell-7.3)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

Add doc for using generic methods

2b7456c

sdwheeler requested a review from daxian-dbw February 1, 2022 21:45

fix typo

884b074

minor edit

28c84c3

daxian-dbw reviewed Feb 1, 2022

View reviewed changes

Feedback edits

57d5454

sdwheeler added 2 commits February 2, 2022 13:31

Add example generic method that takes no parameter

1079c4a

Fix formatting

4ac49c9

sdwheeler merged commit ba325e4 into MicrosoftDocs:staging Feb 2, 2022

sdwheeler deleted the sdw-i8533 branch February 3, 2022 17:21

Fixes #8533 - Add doc for using generic methods #8554

Fixes #8533 - Add doc for using generic methods #8554

Uh oh!

Conversation

sdwheeler commented Feb 1, 2022 • edited by DCtheGeek Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Context

PR Checklist

Uh oh!

opbld31 commented Feb 1, 2022

✅ Validation status: passed

Uh oh!

opbld33 commented Feb 1, 2022

❌ Validation status: errors

Uh oh!

opbld33 commented Feb 1, 2022

✅ Validation status: passed

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daxian-dbw Feb 2, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

opbld30 commented Feb 2, 2022

✅ Validation status: passed

Uh oh!

opbld33 commented Feb 2, 2022

✅ Validation status: passed

Uh oh!

opbld30 commented Feb 2, 2022

✅ Validation status: passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

sdwheeler commented Feb 1, 2022 •

edited by DCtheGeek

Loading

daxian-dbw Feb 2, 2022 •

edited

Loading