记录Powershell模块和脚本

Question

随着Powershell 5引入OOP Classes支持,功能,脚本和模块的传统基于注释的 Powershell文档方法不再适用.Get-Help没有对类,方法或属性提供任何帮助,看起来它将保持这种方式.除此之外,Get-Help在尝试查找特定函数的信息时没有太多帮助,而实际上没有相关的模块或PowerShell脚本.

由于类对于更复杂的Powershell项目特别有用,因此对最新文档的需求比以往任何时候都更迫切.像Doxygen和Sandcastle帮助文件生成器这样的项目确实支持许多OO语言的帮助生成,但似乎无法处理Powershell代码.就让我们来看看在PoshBuild项目表明,它是针对.NET语言的项目,也和需要集成到Visual Studio生成过程,其中纯PowerShell代码没有.

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

那么,如果有的话,我如何自动生成合理的文档

1. .ps1脚本
2. .psm1模块
3. 我的Powershell代码中的类

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

Answer 1

@trebleCode 仍然值得答案，我只是将其发布给任何感兴趣的人。

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

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

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

# References: 
# https://learn-powershell.net/2015/08/07/invoking-private-static-methods-using-powershell/
# /sf/ask/88145571/
# /sf/ask/1095685951/
# 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