関数 ヘルプのドキュメント

PowerShell Coreが提供している関数の機能に関しては前回まででひととおり説明を終えた。今回は関数に書き込むコメントについて取り上げる。

PowerShell Coreでは関数内部または関数の直前にヘルプで表示されるドキュメントをコメントとして書けるようになっている。ある程度関数を使うようになったら、関数にヘルプ向けのドキュメントを書くようにしたい。

ヘルプに出力されるドキュメントはXMLファイルに独立して書いておくこともできる。このあたりは好きな方を使ってもらえればよいが、ここでは関数の中にコメントの形でヘルプのドキュメントを書くお手軽な方法を紹介する。

ヘルプの確認

まず、以前取り上げた関数を、ヘルプのドキュメントを書かない状態で利用するとどうなるかを確認する。

大文字と小文字を変換するDo-FilterTest関数

PS /Users/daichi> function Do-FilterTest
>> {
>>     Param([switch]$upper,[switch]$lower)
>>
>>     Process
>>     {
>>         if ($upper) {$_.ToUpper()}
>>         elseif ($lower) {$_.ToLower()}
>>         else {$_}
>>     }
>> }
PS /Users/daichi> "a","B","c","D","e" | Do-FilterTest
a
B
c
D
e
PS /Users/daichi> "a","B","c","D","e" | Do-FilterTest -upper
A
B
C
D
E
PS /Users/daichi> "a","B","c","D","e" | Do-FilterTest -lower
a
b
c
d
e
PS /Users/daichi>

この状態でGet-Helpコマンドレットの引数にDo-FilterTestを指定して実行すると、次のようにほぼ空のヘルプが表示される。

空のDo-FilterTest関数のヘルプ

PS /Users/daichi> Get-Help Do-FilterTest

NAME
    Do-FilterTest

SYNTAX
    Do-FilterTest [-upper] [-lower]


ALIASES
    None


REMARKS
    None



PS /Users/daichi>

関数の中にこのヘルプで表示されるドキュメントを追加することができる。

ヘルプドキュメントの記入サンプル

関数の中にヘルプドキュメントを書く方法もいくつかあるが、次のように関数の最後に<# #>で括った領域を用意し、ここにヘルプドキュメントを書くのがわかりやすいのではないだろうか。

「.」キーワードの行でドキュメントの項目を指定し、キーワード行の後にそれに関する説明を追加する。パラメータに関してはキーワードで指定することもできるし、パラメータの前に#に続く形で説明を書くこともできる。

ヘルプドキュメントの記入サンプル

function Do-FilterTest
{
    Param(
        #大文字変換を指定
        [switch]
        $upper,

        #小文字変換を指定
        [switch]
        $lower
    )

    Process
    {
        if ($upper) {$_.ToUpper()}
        elseif ($lower) {$_.ToLower()}
        else {$_}
    }

<#
.SYNOPSIS

大文字小文字を変換する

.DESCRIPTION

フィルタとして機能し、パラメータの指示に応じて大文字への変換や小文字への変換を実施する

.INPUTS

System.String.

.OUTPUTS

System.String. 変換後の文字列データを出力する

.EXAMPLE

PS> "a","B","c","D","e" | Do-FilterTest -upper
A
B
C
D
E
PS>

.EXAMPLE

PS> "a","B","c","D","e" | Do-FilterTest -lower
a
b
c
d
e
PS>

.LINK

https://news.mynavi.jp/itsearch/article/hardware
#>
}

指定できる主なキーワードは次のとおり。

ヘルプドキュメントを書き込んだ関数をPowerShell Coreに流し込むと、次のようになる。それぞれGet-Helpコマンドレットでヘルプが出力されていることを確認できる。

ヘルプドキュメントがコメントに書き込まれた関数をパース

PS /Users/daichi> function Do-FilterTest
>> {
>>     Param(
>>         #大文字変換を指定
>>         [switch]
>>         $upper,
>>
>>         #小文字変換を指定
>>         [switch]
>>         $lower
>>     )
>>
>>     Process
>>     {
>>         if ($upper) {$_.ToUpper()}
>>         elseif ($lower) {$_.ToLower()}
>>         else {$_}
>>     }
>>
>> <#
>> .SYNOPSIS
>>
>> 大文字小文字を変換する
>>
>> .DESCRIPTION
>>
>> フィルタとして機能し、パラメータの指示に応じて大文字への変換や小文字への変換を実施する
>>
>> .INPUTS
>>
>> System.String.
>>
>> .OUTPUTS
>>
>> System.String. 変換後の文字列データを出力する
>>
>> .EXAMPLE
>>
>> PS> "a","B","c","D","e" | Do-FilterTest -upper
>> A
>> B
>> C
>> D
>> E
>> PS>
>>
>> .EXAMPLE
>>
>> PS> "a","B","c","D","e" | Do-FilterTest -lower
>> a
>> b
>> c
>> d
>> e
>> PS>
>>
>> .LINK
>>
>> https://news.mynavi.jp/itsearch/article/hardware
>> #>
>> }
PS /Users/daichi>

Get-Helpで書き込んだヘルプドキュメントが表示されている

PS /Users/daichi> Get-Help Do-FilterTest

NAME
    Do-FilterTest

SYNOPSIS
    大文字小文字を変換する


SYNTAX
    Do-FilterTest [-upper] [-lower] [<CommonParameters>]


DESCRIPTION
    フィルタとして機能し、パラメータの指示に応じて大文字への変換や小文字への変換を実施する


RELATED LINKS
    https://news.mynavi.jp/itsearch/article/hardware

REMARKS
    To see the examples, type: "get-help Do-FilterTest -examples".
    For more information, type: "get-help Do-FilterTest -detailed".
    For technical information, type: "get-help Do-FilterTest -full".
    For online help, type: "get-help Do-FilterTest -online"


PS /Users/daichi>

Get-Helpに-examplesパラメータを指定すると実行サンプルが表示される

PS /Users/daichi> Get-Help Do-FilterTest -examples

NAME
    Do-FilterTest

SYNOPSIS
    大文字小文字を変換する


    -------------------------- EXAMPLE 1 --------------------------

    PS>"a","B","c","D","e" | Do-FilterTest -upper

    A
    B
    C
    D
    E
    PS>




    -------------------------- EXAMPLE 2 --------------------------

    PS>"a","B","c","D","e" | Do-FilterTest -lower

    a
    b
    c
    d
    e
    PS>







PS /Users/daichi>

Get-Helpに-detailedパラメータを指定すると、パラメータの説明とサンプルなども表示される

PS /Users/daichi> Get-Help Do-FilterTest -detailed

NAME
    Do-FilterTest

SYNOPSIS
    大文字小文字を変換する


SYNTAX
    Do-FilterTest [-upper] [-lower] [<CommonParameters>]


DESCRIPTION
    フィルタとして機能し、パラメータの指示に応じて大文字への変換や小文字への変換を実施する


PARAMETERS
    -upper [<SwitchParameter>]
        大文字変換を指定

    -lower [<SwitchParameter>]
        小文字変換を指定

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216)
    .

    -------------------------- EXAMPLE 1 --------------------------

    PS>"a","B","c","D","e" | Do-FilterTest -upper

    A
    B
    C
    D
    E
    PS>




    -------------------------- EXAMPLE 2 --------------------------

    PS>"a","B","c","D","e" | Do-FilterTest -lower

    a
    b
    c
    d
    e
    PS>




REMARKS
    To see the examples, type: "get-help Do-FilterTest -examples".
    For more information, type: "get-help Do-FilterTest -detailed".
    For technical information, type: "get-help Do-FilterTest -full".
    For online help, type: "get-help Do-FilterTest -online"


PS /Users/daichi>

Get-Helpに-fullパラメータを指定すると、さらに多くの情報が表示される

PS /Users/daichi> Get-Help Do-FilterTest -full

NAME
    Do-FilterTest

SYNOPSIS
    大文字小文字を変換する


SYNTAX
    Do-FilterTest [-upper] [-lower] [<CommonParameters>]


DESCRIPTION
    フィルタとして機能し、パラメータの指示に応じて大文字への変換や小文字への変換を実施する


PARAMETERS
    -upper [<SwitchParameter>]
        大文字変換を指定

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -lower [<SwitchParameter>]
        小文字変換を指定

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216)
    .

INPUTS
    System.String.


OUTPUTS
    System.String. 変換後の文字列データを出力する


    -------------------------- EXAMPLE 1 --------------------------

    PS>"a","B","c","D","e" | Do-FilterTest -upper

    A
    B
    C
    D
    E
    PS>




    -------------------------- EXAMPLE 2 --------------------------

    PS>"a","B","c","D","e" | Do-FilterTest -lower

    a
    b
    c
    d
    e
    PS>





RELATED LINKS
    https://news.mynavi.jp/itsearch/article/hardware



PS /Users/daichi>

Get-Helpで-onlineパラメータを指定すると、システムブラウザで.LINKのURIがオープンされる

PS /Users/daichi> Get-Help Do-FilterTest -online
PS /Users/daichi>

こんな感じでヘルプドキュメントを書いておくと、関数のソースコードを読み直さなくても中身の動作がわかるようになる。開発の進め方として、最初にヘルプドキュメントを書いてから、それに沿うように関数の中身を書いていくという方法もある。この方法だとヘルプドキュメントがそのまま仕様書として使えるようになるようなもので、なかなか便利だ。

ヘルプは将来の自分を助けるものだと思って書く癖をつけておくとよい。慣れないとなかなかヘルプドキュメントを書こうとは思わないだろう。

なお、ヘルプは書く位置などに決まりがあるので、他の書き方を知りたい方は「About Comment Based Help」などを参考にしてほしい。

参考資料

• Microsoft PowerShell Module Browser
• Microsoft PowerShell6｜Microsoft.PowerShell.Core｜About｜About Functions
• Microsoft PowerShell6｜Microsoft.PowerShell.Core｜About｜About Comment Based Help