about_Comment_Based_Help — 주석 기반 도움말

함수나 스크립트를 만들면, 이걸 쓸 사람들을 위해 사용법을 문서로 남겨두고 싶어지죠. 그럴 때 도움말 내용을 코드 안의 주석으로 정리해서 넣을 수 있어요. 이걸 '주석 기반 도움말(comment-based help)'이라고 해요. 이 글에서는 전용 도움말 키워드를 이용해서 함수와 스크립트의 도움말을 직접 작성하는 방법을 하나하나 설명할게요.

출처: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help

본문

짧은 설명(Short description)

함수와 스크립트의 도움말 내용을 주석으로 어떻게 작성하는지 설명합니다.

자세한 설명(Long description)

함수나 스크립트의 도움말 내용은 전용 도움말 주석 키워드(help comment keyword)를 써서 작성할 수 있어요. Get-Help cmdlet은 주석 기반 도움말을, XML 파일로 만든 cmdlet 도움말과 동일한 형식으로 화면에 보여줍니다. 사용자는 Get-Help의 Detailed, Full, Examples, Online 같은 모든 매개 변수를 사용해서 주석 기반 도움말의 내용을 확인할 수 있어요.

함수나 스크립트의 도움말은 XML 기반 파일로도 작성할 수 있습니다. Get-Help cmdlet이 XML 기반 도움말 파일을 찾도록 하려면 .EXTERNALHELP 키워드를 써야 해요. 이 키워드가 없으면 Get-Help는 함수나 스크립트의 XML 기반 도움말을 찾지 못해요.

이 항목에서는 함수와 스크립트의 도움말을 작성하는 방법을 다룰게요. 함수나 스크립트의 도움말을 화면에 표시하는 방법은 Get-Help를 참고하세요.

Update-Help와 Save-Help cmdlet은 XML 파일에서만 동작해요. Updatable Help는 주석 기반 도움말을 지원하지 않아요.

주석 기반 도움말의 문법(Syntax for comment-based help)

주석 기반 도움말을 만들 때는 한 줄 주석과 블록 주석, 두 가지 주석 스타일 중 원하는 것을 쓰면 돼요.

주석 기반 도움말의 문법은 다음과 같아요.

# .<help keyword>
# <help content>

또는,

<#
    .<help keyword>
    <help content>
#>

주석 기반 도움말은 연속된 주석들로 작성됩니다. 각 줄 앞에 주석 기호 #을 붙일 수도 있고, <#와 #> 기호로 주석 블록을 만들 수도 있어요. 주석 블록 안의 모든 줄은 주석으로 처리되어요.

주석 기반 도움말 항목의 모든 줄은 서로 붙어 있어야 합니다. 도움말 항목의 일부가 아닌 주석이 도움말 항목 앞에 오는 경우, 마지막 비도움말 주석 줄과 도움말 시작 부분 사이에 빈 줄이 최소 하나 이상 있어야 해요.

도움말의 각 구획은 키워드로 정의됩니다. 각 주석 기반 도움말 키워드 앞에는 점 .이 붙어요. 키워드는 어떤 순서로 써도 상관없고, 키워드 이름은 대소문자를 구분하지 않아요.

예를 들어, .DESCRIPTION 키워드는 함수나 스크립트에 대한 설명 앞에 옵니다.

<#
.DESCRIPTION
Get-Function displays the name and syntax of all functions in the session.
#>

주석 블록에는 키워드가 최소 하나는 들어 있어야 해요. .EXAMPLE처럼 일부 키워드는 같은 주석 블록 안에 여러 번 나타날 수 있어요. 키워드의 도움말 내용은 키워드 다음 줄부터 시작하며, 여러 줄에 걸쳐 쓸 수 있어요.

함수에서의 주석 기반 도움말 문법(Syntax for comment-based help in functions)

함수의 주석 기반 도움말은 다음 세 위치 중 한 곳에 둘 수 있어요.

함수 본문의 맨 앞.
함수 본문의 맨 끝.
function 키워드 앞. 함수 도움말의 마지막 줄과 function 키워드 사이에는 빈 줄이 두 줄을 초과하면 안 돼요.

예를 들어:

function Get-Function {
    <#
        .<help keyword>
        <help content>
    #>

    # function logic
}

또는:

function Get-Function {
    # function logic

    <#
        .<help keyword>
        <help content>
    #>
}

또는:

<#
    .<help keyword>
    <help content>
#>
function Get-Function { }

스크립트에서의 주석 기반 도움말 문법(Syntax for comment-based help in scripts)

스크립트의 주석 기반 도움말은 스크립트 안의 다음 두 위치 중 한 곳에 둘 수 있어요.

스크립트 파일의 맨 앞. 스크립트 도움말 앞에는 주석과 빈 줄만 올 수 있어요. 스크립트 본문의 첫 항목이(도움말 뒤에) 함수 선언이라면, 스크립트 도움말의 끝과 함수 선언 사이에 빈 줄이 최소 두 줄 있어야 합니다. 그렇지 않으면 도움말이 스크립트가 아닌 함수의 도움말로 해석돼요.
스크립트 파일의 맨 끝. 다만 스크립트에 서명(signature)이 있다면 주석 기반 도움말을 스크립트 파일의 맨 앞에 두세요. 서명 블록이 스크립트의 끝을 차지하기 때문이에요.

예를 들어:

<#
.<help keyword>
<help content>
#>
function Get-Function { }

또는:

function Get-Function { }
<#
.<help keyword>
<help content>
#>

주석 기반 도움말 키워드(Comment-based help keywords)

다음은 사용할 수 있는 주석 기반 도움말 키워드들이에요. 이 키워드들은 주석 기반 도움말 안에서 어떤 순서로든 나타날 수 있고, 대소문자를 구분하지 않아요. 이 글에서는 도움말 항목에서 보통 나타나는 순서대로 키워드를 나열했어요.

.SYNOPSIS

함수나 스크립트에 대한 간결한 설명이에요. 각 항목마다 이 키워드는 한 번만 쓸 수 있어요.

.DESCRIPTION

함수나 스크립트에 대한 자세한 설명이에요. 각 항목마다 이 키워드는 한 번만 쓸 수 있어요.

.PARAMETER

매개 변수에 대한 설명이에요. 함수나 스크립트 문법에 있는 매개 변수마다 .PARAMETER 키워드를 하나씩 추가하세요.

매개 변수 이름은 .PARAMETER 키워드와 같은 줄에 입력하고, 매개 변수 설명은 .PARAMETER 키워드 다음 줄들에 입력해요. Windows PowerShell은 .PARAMETER 줄과 다음 키워드 또는 주석 블록의 끝 사이의 모든 텍스트를 매개 변수 설명의 일부로 해석합니다. 설명에는 문단 구분을 넣을 수도 있어요.

.PARAMETER  <Parameter-Name>

Parameter 키워드는 주석 블록 안에서 어떤 순서로든 나타날 수 있지만, 도움말 항목에 나타나는 매개 변수(와 그 설명)의 순서는 함수나 스크립트 문법이 결정해요. 순서를 바꾸고 싶으면 문법을 변경해야 해요.

매개 변수 변수 이름 바로 앞에 있는 함수나 스크립트 문법에 주석을 넣는 방식으로도 매개 변수 설명을 지정할 수 있어요. 그러려면 키워드가 최소 하나 들어 있는 주석 블록도 함께 있어야 해요.

문법 주석과 .PARAMETER 키워드를 둘 다 쓰면, .PARAMETER 키워드와 연결된 설명이 사용되고 문법 주석은 무시됩니다.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .PARAMETER
        [string]$ComputerName
    )
    # Verb the Noun on the computer
}

`.EXAMPLE`

함수나 스크립트를 사용하는 예시 명령이에요. 선택적으로 예시 출력과 설명을 덧붙일 수 있어요. 예시마다 이 키워드를 반복하세요.

`.INPUTS`

함수나 스크립트로 파이프라인을 통해 입력할 수 있는 개체의 .NET 형식이에요. 입력 개체에 대한 설명도 포함할 수 있어요. 입력 형식마다 이 키워드를 반복하세요.

`.OUTPUTS`

cmdlet이 반환하는 개체의 .NET 형식이에요. 반환되는 개체에 대한 설명도 포함할 수 있어요. 출력 형식마다 이 키워드를 반복하세요.

`.NOTES`

함수나 스크립트에 대한 추가 정보예요.

`.LINK`

관련 항목의 이름이에요. 관련 항목마다 이 키워드를 반복해요. 이 내용은 도움말 항목의 Related Links 구획에 표시됩니다.

.LINK 키워드 내용에는 같은 도움말 항목의 온라인 버전을 가리키는 URI(Uniform Resource Identifier)도 포함할 수 있어요. Get-Help의 Online 매개 변수를 사용하면 온라인 버전이 열려요. URI는 반드시 http나 https로 시작해야 해요.

`.COMPONENT`

함수나 스크립트가 사용하거나 관련된 기술 또는 기능의 이름이에요. Get-Help의 Component 매개 변수는 이 값을 사용해서 검색 결과를 필터링해요.

`.ROLE`

도움말 항목에 대한 사용자 역할의 이름이에요. Get-Help의 Role 매개 변수는 이 값을 사용해서 검색 결과를 필터링해요.

`.FUNCTIONALITY`

함수의 의도된 용도를 설명하는 키워드들이에요. Get-Help의 Functionality 매개 변수는 이 값을 사용해서 검색 결과를 필터링해요.

`.FORWARDHELPTARGETNAME <Command-Name>`

지정한 명령의 도움말 항목으로 이동시켜요. 함수, 스크립트, cmdlet, 공급자(provider)의 도움말 내용을 포함해 어떤 도움말 항목으로든 사용자를 이동시킬 수 있어요.

# .FORWARDHELPTARGETNAME <Command-Name>

`.FORWARDHELPCATEGORY`

.FORWARDHELPTARGETNAME에 있는 항목의 도움말 범주를 지정해요. 사용할 수 있는 값은 Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter, All이에요. 이름이 같은 명령이 있을 때 충돌을 피하려면 이 키워드를 사용하세요.

# .FORWARDHELPCATEGORY <Category>

`.REMOTEHELPRUNSPACE <PSSession-variable>`

도움말 항목을 담고 있는 세션을 지정해요. PSSession 개체를 담고 있는 변수를 입력하세요. Export-PSSession cmdlet이 내보낸 명령의 도움말 내용을 찾을 때 이 키워드를 사용합니다.

# .REMOTEHELPRUNSPACE <PSSession-variable>

`.EXTERNALHELP`

스크립트나 함수의 XML 기반 도움말 파일을 지정해요.

# .EXTERNALHELP <XML Help File>

함수나 스크립트가 XML 파일로 문서화되어 있다면 .EXTERNALHELP 키워드가 필요해요. 이 키워드가 없으면 Get-Help는 함수나 스크립트의 XML 기반 도움말 파일을 찾을 수 없어요.

.EXTERNALHELP 키워드는 다른 주석 기반 도움말 키워드보다 우선해요. .EXTERNALHELP가 있으면, Get-Help가 .EXTERNALHELP 키워드 값과 일치하는 도움말 항목을 찾지 못하더라도 주석 기반 도움말을 표시하지 않아요.

함수가 모듈에서 내보내지는 경우, .EXTERNALHELP 키워드 값을 경로가 없는 파일 이름으로 설정하세요. Get-Help는 모듈 디렉터리의 언어별 하위 디렉터리에서 해당 파일 이름을 찾아요. 함수의 XML 기반 도움말 파일 이름에는 그 어떤 규칙도 없어요. PowerShell 5.0부터 모듈에서 내보내지는 함수는 모듈 이름으로 지정된 도움말 파일에 문서화할 수 있어요. .EXTERNALHELP 주석 키워드를 쓸 필요가 없습니다. 예를 들어 MyModule 모듈에서 Test-Function 함수를 내보낸다면, 도움말 파일 이름을 MyModule-help.xml로 지을 수 있어요. Get-Help cmdlet은 모듈 디렉터리의 MyModule-help.xml 파일에서 Test-Function 함수의 도움말을 찾습니다.

함수가 모듈에 포함되지 않았다면 XML 기반 도움말 파일의 경로를 포함하세요. 값에 경로가 있고 그 경로에 UI 문화권별 하위 디렉터리가 있다면, Get-Help는 모듈 디렉터리에서와 마찬가지로 Windows에 정립된 언어 폴백 표준에 따라 스크립트나 함수 이름의 XML 파일을 하위 디렉터리에서 재귀적으로 검색해요.

cmdlet 도움말 XML 기반 도움말 파일 형식에 대한 자세한 내용은 How to Write Cmdlet Help를 참고하세요.

자동 생성되는 내용(Autogenerated content)

이름(Name), 문법(Syntax), 매개 변수 목록(parameter list), 매개 변수 특성 표(parameter attribute table), 공통 매개 변수(common parameters), 설명(remarks)은 Get-Help cmdlet이 자동으로 생성해요.

Name

함수 도움말 항목의 Name 구획은 함수 문법에 있는 함수 이름에서 가져와요. 스크립트 도움말 항목의 Name은 스크립트 파일 이름에서 가져옵니다. 이름이나 대소문자를 바꾸려면 함수 문법이나 스크립트 파일 이름을 변경해야 해요.

Syntax

도움말 항목의 Syntax 구획은 함수나 스크립트 문법에서 생성됩니다. 매개 변수의 .NET 형식 같은 세부 정보를 도움말 항목 문법에 추가하고 싶다면, 그 세부 정보를 문법에 추가하세요. 매개 변수 형식을 지정하지 않으면 기본값으로 Object 형식이 삽입돼요.

Parameter list

도움말 항목의 매개 변수 목록은 함수나 스크립트 문법과, .PARAMETER 키워드로 추가한 설명에서 생성돼요. 함수 매개 변수는 함수나 스크립트 문법에 나타나는 순서와 동일한 순서로 도움말 항목의 Parameters 구획에 표시됩니다. 매개 변수 이름의 철자와 대소문자도 문법에서 가져와요. .PARAMETER 키워드로 지정한 매개 변수 이름의 영향을 받지 않습니다.

Common Parameters

Common parameters(공통 매개 변수)는 실제로 아무 효과가 없어도 도움말 항목의 문법과 매개 변수 목록에 추가됩니다. 공통 매개 변수에 대한 자세한 내용은 about_CommonParameters를 참고하세요.

Parameter attribute table

Get-Help는 Full 또는 Parameter 매개 변수를 사용할 때 나타나는 매개 변수 특성 표를 생성해요. Required, Position, Default 특성 값은 함수나 스크립트 문법에서 가져와요.

기본값과 Accept Wildcard characters 값은 함수나 스크립트에 정의되어 있어도 매개 변수 특성 표에 나타나지 않아요. 사용자를 돕기 위해 이 정보를 매개 변수 설명에 제공하세요.

Remarks

도움말 항목의 Remarks 구획은 함수나 스크립트 이름에서 자동으로 생성돼요. 그 내용은 변경하거나 영향을 줄 수 없어요.

예제(Examples)

함수에 대한 주석 기반 도움말(Comment-based Help for a Function)

다음 예제 함수에는 주석 기반 도움말이 포함되어 있어요.

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$Name = $Name + "." + $Extension
$Name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-Extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

결과는 다음과 같아요.

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"Get-Help about_CommonParameters".

INPUTS
None. You can't pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-Extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

함수 문법의 매개 변수 설명(Parameter Descriptions in Function Syntax)

이 예제는 앞선 예제와 같지만, 매개 변수 설명을 함수 문법 안에 넣었어요. 설명이 짧을 때 가장 유용한 형식이에요.

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$Name,

[string]
#Specifies the file name extension. "Txt" is the default.
$Extension = "txt"
)

$Name = $Name + "." + $Extension
$Name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-Extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

스크립트에 대한 주석 기반 도움말(Comment-based Help for a Script)

다음 예제 스크립트에는 주석 기반 도움말이 포함되어 있어요. 닫는 #>와 param 문 사이의 빈 줄에 주목하세요. param 문이 없는 스크립트에서는 도움말 항목의 마지막 주석과 첫 번째 함수 선언 사이에 빈 줄이 최소 두 줄 있어야 해요. 이 빈 줄이 없으면 Get-Help가 도움말 항목을 스크립트가 아닌 함수와 연결해 버려요.

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutputPath)

function Get-Data { }
...

다음 명령은 스크립트 도움말을 가져와요. 스크립트가 $Env:PATH 환경 변수에 나열된 디렉터리에 없으므로, 스크립트 도움말을 가져오는 Get-Help 명령에 스크립트 경로를 지정해야 해요.

Get-Help -Name .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"Get-Help about_CommonParameters".

# INPUTS

None. You can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath
C:\Reports\2009\January.csv

# RELATED LINKS

XML 파일로 연결하기(Redirecting to an XML File)

함수와 스크립트의 도움말 내용은 XML 기반으로도 작성할 수 있어요. 주석 기반 도움말이 구현하기는 더 쉽지만, Updatable Help와 여러 언어로 된 도움말을 제공하려면 XML 기반 도움말이 필요해요.

다음 예제는 Update-Month.ps1 스크립트의 처음 몇 줄을 보여줘요. 이 스크립트는 .EXTERNALHELP 키워드를 사용해서 스크립트의 XML 기반 도움말 항목 경로를 지정합니다.

.EXTERNALHELP 키워드의 값은 키워드와 같은 줄에 나타나야 한다는 점에 주의하세요. 그 외의 배치는 효과가 없어요.

# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutputPath)
function Get-Data { }
...

다음 예제들은 함수에서 .EXTERNALHELP 키워드를 배치할 수 있는 세 가지 유효한 위치를 보여줘요.

function Add-Extension {
    # .EXTERNALHELP C:\ps-test\Add-Extension.xml

    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

function Add-Extension {
    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name

    # .EXTERNALHELP C:\ps-test\Add-Extension.xml
}

# .EXTERNALHELP C:\ps-test\Add-Extension.xml
function Add-Extension {
    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

다른 도움말 항목으로 연결하기(Redirecting to a Different Help Topic)

다음 코드는 PowerShell에 내장된 help 함수의 시작 부분에서 가져온 거예요. 이 함수는 도움말 텍스트를 한 화면씩 표시합니다. Get-Help cmdlet의 도움말 항목이 help 함수를 설명하므로, help 함수는 .FORWARDHELPTARGETNAME과 .FORWARDHELPCATEGORY 키워드를 사용해서 사용자를 Get-Help cmdlet 도움말 항목으로 이동시켜요.

function help {
    <#
    .FORWARDHELPTARGETNAME Get-Help
    .FORWARDHELPCATEGORY Cmdlet
    #>

    [CmdletBinding(DefaultParameterSetName='AllUsersView')]
    param(
        [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
        [System.String]
        ${Name},
    ...

다음 명령은 이 기능을 사용해요.

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

about_Comment_Based_Help — 주석 기반 도움말