Question

使用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或降价格式的模块生成文档，如果它支持类，这几乎就是我想要的。

那么，如果我有

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

.ps1脚本
.psm1 modules
类

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

Answer 1

@trebleCode仍然值得回答，我只是将其发布给有兴趣的人。

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

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

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

# 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

记录Powershell模块和脚本

1 个答案: