Document the three return shapes of PSSerializer.Deserialize - #27889
Document the three return shapes of PSSerializer.Deserialize#27889Egor Sidorenko (esidorenko-sl) wants to merge 6 commits into
Conversation
The XML doc comment for PSSerializer.Deserialize only said it returns an object representing the serialized content. In practice it returns null when the CliXml has no objects, the object itself when there is exactly one, and an object array when there are several. This was undocumented and callers had to find out by trial and error. Update the doc comment to state the three shapes explicitly and point readers at DeserializeAsList when they want a stable collection type back. No behavior change.
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
There was a problem hiding this comment.
Pull request overview
Updates the XML documentation for PSSerializer.Deserialize to explicitly describe its three possible return shapes (null / scalar / array) and to point callers to DeserializeAsList when a consistent array return type is required.
Changes:
- Expand
<returns>docs forPSSerializer.Deserializeto describe the 0/1/N object return behavior. - Add guidance to use
DeserializeAsList(string)when a stable collection return type is needed.
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
| /// <see langword="null"/> if it contains no objects, the single deserialized object if it | ||
| /// contains exactly one, or an <see cref="object"/> array if it contains more than one. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
I looked for this notation in the repo before applying it: |
PR Summary
PSSerializer.Deserializereturns one of three different shapes depending on how many objects the CliXml holds. It returnsnullwhen there are none, the bare object when there is exactly one, and anobject[]when there are several. The doc comment only said it returns "an object that represents the serialized content", so a caller expecting a collection gets a scalar back for single item input and has to find that out by running into it.This updates the XML doc comment to state the three shapes and to point at
DeserializeAsList, which always returns an array, for callers who want a stable return type.Documentation only. No behaviour change.
PR Context
The behaviour itself is intentional and matches how a single item pipeline behaves in PowerShell, so I have not touched the implementation. The only problem is that none of it was written down, while the alternative method that avoids the collapse is public and went unmentioned.
PR Checklist
.h,.cpp,.cs,.ps1and.psm1files have the correct copyright headerWIP:or[ WIP ]to the beginning of the title and remove the prefix when the PR is ready.