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

【連載】

PowerShell Core入門 - 基本コマンドの使い方

【第43回】関数 ヘルプのドキュメント

[2019/03/22 07:00]後藤大地 ブックマーク ブックマーク

  • サーバ/ストレージ

サーバ/ストレージ

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

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
#>
}

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

キーワード 内容
.SYNOPSIS 関数の簡単な説明
.DESCRIPTION 関数の詳しい説明
.PARAMETER パラメータの説明
.EXAMPLE 関数の使用例
.INPUTS パイプで接続できるオブジェクトの型
.OUTPUTS 関数が返すオブジェクトの型
.NOTES 関数に関する追加情報
.LINK 関連するキーワードまたはURI
.COMPONENT 関数が使用している技術や機能

ヘルプドキュメントを書き込んだ関数を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」などを参考にしてほしい。

参考資料

※ 本記事は掲載時点の情報であり、最新のものとは異なる場合がございます。予めご了承ください。

一覧はこちら

連載目次

もっと知りたい!こちらもオススメ

【連載】RPA入門 - ツールで学ぶ活用シーン

【連載】RPA入門 - ツールで学ぶ活用シーン

AIには、ルールベース、機械学習、深層学習(ディープラーニング)の3つのレベルがあり、レベルが上がるに連れてより高度な人工知能を実現しますが、AIのスピンオフという位置付けで、Digital Labor(仮想知的労働者)によるホワイトカラー業務の自動化を実現するRPAが注目されています。

関連リンク

この記事に興味を持ったら"いいね!"を Click
Facebook で IT Search+ の人気記事をお届けします

会員登録(無料)

注目の特集/連載
[解説動画] Googleアナリティクス分析&活用講座 - Webサイト改善の正しい考え方
[解説動画] 個人の業務効率化術 - 短時間集中はこうして作る
ミッションステートメント
教えてカナコさん! これならわかるAI入門
知りたい! カナコさん 皆で話そうAIのコト
対話システムをつくろう! Python超入門
Kubernetes入門
AWSで作るクラウドネイティブアプリケーションの基本
PowerShell Core入門
徹底研究! ハイブリッドクラウド
マイナビニュース スペシャルセミナー 講演レポート/当日講演資料 まとめ
セキュリティアワード特設ページ

一覧はこちら

今注目のIT用語の意味を事典でチェック!

一覧はこちら

ページの先頭に戻る