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
Sorry, something went wrong.
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. |
Sorry, something went wrong.
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 for PSSerializer.Deserialize to 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.
Sorry, something went wrong.
| /// <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: <see cref="X"/>[] does not appear anywhere under src/. [] inside a cref is only ever used in method signatures there (cref="string.Format(IFormatProvider,string,object[])" and similar). The prose form is what the codebase actually uses, e.g. MshHostRawUserInterface.cs:1425 has Copies the <see cref="...BufferCell"/> array into the screen buffer, which is the same shape as the line here. The method's declared return type is already object[] in the signature, so I'd rather keep the sentence idiomatic than introduce a one-off notation. Happy to change it if a maintainer prefers otherwise. |
Sorry, something went wrong.
PR Summary
PSSerializer.Deserialize returns one of three different shapes depending on how many objects the CliXml holds. It returns null when there are none, the bare object when there is exactly one, and an object[] 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