编写PowerShell模块文档时，OUTPUTS部分的输出类型描述应多具体？

核心判断 #

既不能偷懒填System.Object应付，也不能只甩一堆复杂类型名不给普通用户解释，文档需要同时覆盖两类读者的需求：

• 对需要精确类型信息的开发者、深度使用用户：提供完整、准确的输出类型清单
• 对只需要基础功能的普通终端用户：降低理解门槛，避免无意义的类型焦虑

具体填写规则 #

• 必须列全所有可能的精确输出类型，严禁笼统填写System.Object
  PlatyPS对输出段的解析逻辑和PowerShell内置的输出类型查询能力是绑定的：用户运行 Get-Command <你的Cmdlet> | Select-Object -ExpandProperty OutputType 时，读到的就是你在这个部分写的类型信息。
  如果直接填System.Object，等于完全废掉这个查询能力：不管是开发者写强类型校验脚本，还是普通用户预判管道传递的兼容性，都拿不到有效参考。哪怕是你模块内定义的自定义类型（比如示例里提到的ReferencedAssembly.Foo.ThingieX、ReferencedAssembly.Foo.ThingieY这类），也要老老实实把完整类型全名列出来。
• 给每个输出类型配套面向普通用户的低门槛说明
  不要只把类型名堆在段落里就结束，紧跟一段和日常使用相关的解释：

  普通用户无需记忆上述完整类型名称：

  • 所有自定义输出类型都内置统一的通用属性（如Id、Name、Status），可直接配合Select-Object、Where-Object等常用命令操作，不需要单独处理复杂类型的解析逻辑
  • 不同类型的触发规则会在参数说明部分明确标注，比如默认运行时返回精简统计对象，指定-FullDetail参数时返回完整明细对象

• 补充特殊场景的输出说明
  • 如果cmdlet在特定条件下无任何管道输出（比如输入路径不存在时直接静默返回），要明确标注触发场景，不要让用户误以为输出丢失
  • 如果cmdlet除了核心自定义对象外，还会输出通用类型（比如System.String类型的进度提示、System.Boolean类型的执行状态标记），也要完整列入类型清单，不要遗漏

常见认知误区澄清 #

用户反感的从来不是文档里出现复杂的类型名，而是“文档只甩类型名、没有任何实际使用指引”的敷衍感。

• 对普通用户：只要说明清楚“这个输出可以直接正常接管道操作，你不用管它内部的类型细节”，根本不会因为看到长类型名产生畏难情绪
• 对开发者、深度用户：精确的类型清单反而是模块文档规范性的核心标志，会大幅提升模块的可靠度

内容的提问来源于stack exchange，提问作者Rno