记录 Powershell 模块和脚本答案

【问题标题】：Documenting Powershell modules and scripts记录 Powershell 模块和脚本
【发布时间】：2018-07-17 14:38:38
【问题描述】：

使用Powershell 5 introducing OOP Classes support，用于函数、脚本和模块的传统comment-based Powershell 文档方法不再适合。 Get-Help 没有为类、方法或属性提供任何帮助，看起来它将保持这种状态。除此之外，Get-Help 在尝试查找有关特定功能的信息时并没有太大帮助，而实际上没有相关的模块或 powershell 脚本。

由于类对于更复杂的 Powershell 项目特别有用，因此对最新文档的需求比以往任何时候都更加紧迫。像Doxygen 和Sandcastle Help File Builder 这样的项目确实支持许多OO 语言的帮助生成，但似乎不能处理Powershell 代码。快速浏览一下PoshBuild project 会发现它也针对 .NET 语言项目，需要集成到 Visual Studio 构建过程中，而纯 Powershell 代码没有。

还有 PSDoc 能够基于 Get-Help 输出为 HTML 或 markdown 格式的模块生成文档，如果它支持类，这将是我想要的。

如果我有，我该如何自动生成合理的文档

.ps1 脚本
.psm1 模块
Powershell 代码中的类

使用基于注释的帮助文档语法？

【问题讨论】：

为什么不直接分叉 PsDoc 并为您的课程推出自定义解决方案？或者看看 The Classy PlatyPS 模块，它支持类和枚举：get-powershellblog.blogspot.com/2017/05/…
我想我一定是在过去的某个地方偶然发现了 PSRAW 的 Classy PlatyPS 并且出于某种原因将其驳回。但乍一看，它看起来非常有用。感谢您提请我注意。
没问题。如果我将其发布为答案，您可以将其标记为答案吗？
@trebleCode 确定，继续

标签： powershell documentation

【解决方案1】：

@trebleCode 仍然值得回答，我只是为感兴趣的人发帖。

我不久前开始尝试回答这个问题，但分心了，一直没有完成。如果我没记错的话，我在 Github 上发现了一些讨论，他们说他们不打算支持带有注释的类，这很可悲，因为我喜欢 Powershell Comments。

我的想法是，通过调用内置帮助方法，您可以创建一个帮助函数，该函数将检测类关键字上方的这些非标准 cmets，并将它们转换为注释对象，而无需调用 get-help。这些 cmets 也可以存储在外部文件中。

下面我找到了将cmets解析为对象并在代码中创建注释对象的代码。

# References: 
# https://learn-powershell.net/2015/08/07/invoking-private-static-methods-using-powershell/
# https://stackoverflow.com/questions/1259222/how-to-access-internal-class-using-reflection
# https://stackoverflow.com/questions/15652656/get-return-value-after-invoking-a-method-from-dll-using-reflection
# https://github.com/PowerShell/PowerShell/blob/a8627b83e5cea71c3576871eacad7f2b19826d53/src/System.Management.Automation/help/HelpCommentsParser.cs

$ExampleComment = @"
<#
.SYNOPSIS
    This was a triumph
#>
"@

$CommentLines = [Collections.Generic.List`1[String]]::new()
$InvokeArgs = @($ExampleComment, $CommentLines)

# GetMethod Filter
$BindingFlags = 'static','nonpublic','instance'

# GetMethod Filter: We need to specify overloaded methods by their parameters
$ParamTypes  = [Type]::GetTypeArray($InvokeArgs)
$ParamCount  = [System.Reflection.ParameterModifier]::new(2)

$HelpParser  = [psobject].Assembly.GetType('System.Management.Automation.HelpCommentsParser')
$CollectCommentText = $HelpParser.GetMethod('CollectCommentText', $BindingFlags, $null, $ParamTypes, $ParamCount)

# Extension methods aren't part of the class so null gets called first.
# TODO: Figure out return value
$CollectCommentText.Invoke($Null,$InvokeArgs)
$InvokeArgs

# Comment object but properties are read only.
$CommentHelp = [System.Management.Automation.Language.CommentHelpInfo]::new()
$CommentHelp.Synopsis
$CommentHelp.Description
$CommentHelp.Examples
$CommentHelp

【讨论】：