PowerShell 스크립트에 대한 설명 기반 도움말 작성

1. PowerShell의 주석 기반 도움말
2. PowerShell의 주석 기반 키워드

이 문서에서는 스크립트 및 함수에 대한 주석 기반 도움말 항목을 작성하는 방법을 보여줍니다. 우리는 주제를 만들기 위해 특별 도움말 주석 키워드를 사용할 것입니다.

Get-Help cmdlet을 사용하여 XML 파일에서 생성된 항목과 유사한 주석 기반 도움말 항목을 표시합니다.

PowerShell의 주석 기반 도움말

아래 그림은 주석 기반 도움말의 구문입니다.

# .<help keyword>
# <help content>

또는

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

댓글 기반 도움말 항목을 일련의 댓글로 작성합니다. 주석을 표시하려면 모든 주석 행의 시작 부분에 # 기호를 추가하거나 <# 및 #>를 사용하여 주석 블록을 만들 수 있습니다.

콘솔은 주석 블록 내의 행을 주석으로 등록합니다.

주석 기반 주제 도움말의 각 섹션을 정의하기 위해 특수 키워드를 사용합니다. 키워드는 .로 시작합니다. 대/소문자를 구분하지 않습니다.

다음은 예입니다.

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

위의 예에서 .Description 키워드는 주석을 함수의 설명으로 표시합니다.

주석 블록에는 하나 이상의 키워드가 있어야 합니다. 일부 키워드는 한 번만 표시되는 반면 다른 키워드는 제한이 없습니다.

키워드 내용은 키워드 바로 다음 줄에서 시작해야 하며 제한이 없습니다.

기능에 대한 주석 기반 도움말을 추가할 때 아래 설명된 세 위치 중 하나에 도움말을 추가할 수 있습니다.

1. 함수 본문의 시작 부분.
2. 함수 본문의 끝.
3. function 키워드 앞. 한 줄 이하의 빈 줄로 구분됩니다.

예:

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

  # function logic
}

또는

function Get-Function
{
   # function logic

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

또는

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

스크립트에 대한 주석 기반 도움말은 스크립트 시작 부분이나 끝에 나타날 수 있습니다. 여기 몇 가지 예가 있어요.

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

function Get-Function { }

또는

function Get-Function { }

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

PowerShell의 주석 기반 키워드

다음은 유효한 주석 기반 도움말 키워드입니다. 어떤 순서로든 나타날 수 있으며 대소문자를 구분하지 않습니다.

.시놉시스

함수 또는 스크립트에 대한 간단한 설명입니다. 키워드는 각 주제에 한 번만 나타나야 합니다.

.설명

함수 또는 스크립트에 대한 자세한 설명입니다. 각 항목에서 한 번만 사용합니다.

.파라미터

스크립트 또는 함수의 매개변수를 설명합니다. 스크립트 또는 함수의 모든 매개변수에 .PARAMETER 키워드를 추가합니다.

.PARAMETER <Parameter-Name>

매개변수 키워드는 주석 블록에서 엄격한 순서를 따르지 않습니다. 스크립트 또는 함수의 매개변수 구문에 따라 도움말 항목의 순서가 결정됩니다.

구문을 변경하여 순서를 변경할 수 있습니다.

함수나 스크립트에 주석을 추가하여 매개변수 키워드 내용을 지정할 수 있습니다. 이 주석은 매개 변수 변수 이름 앞에 와야 합니다.

PowerShell은 둘 다 사용되는 구문 주석보다 매개 변수 키워드와 관련된 설명을 우선시합니다.

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.예제

스크립트 또는 함수를 사용하는 샘플 명령을 포함합니다. 스크립트나 함수의 모든 예제에 이 키워드를 포함할 수 있습니다.

.입력

이들은 스크립트 또는 함수로 파이프할 수 있는 .NET 개체입니다. 입력 개체에 대한 설명을 추가할 수 있습니다.

.출력

이들은 cmdlet이 반환하는 .NET 개체입니다. 반환된 개체에 대한 설명을 추가할 수 있습니다.

.참고

스크립트 또는 함수에 대한 추가 정보입니다. 정보에는 코딩된 날짜, 함수 이름 또는 제작자 이름이 포함될 수 있습니다.

.LINK

관련 항목입니다.

다음은 함수에 대한 주석 기반 도움말의 예입니다.

결론적으로 주석 블록에 배치하여 함수 또는 스크립트에 주석 기반 도움말을 추가할 수 있습니다. 도움말 항목을 추가할 때 위에서 논의한 키워드를 사용하고 스크립트 및 기능에 대한 주석 블록을 배치할 위치를 기억하십시오.