OT CLI 명령어 업데이트

GitHub에서 소스 보기

CLI 명령어는 openthread GitHub 저장소의 CLI 소스 파일에서 생성됩니다.

이 가이드에서는 명령어 목록을 만드는 데 사용하는 커스텀 Doxygen 주석을 사용하는 방법을 안내합니다.

시작하기

CLI 명령어를 문서화하려면 다음 단계를 완료하세요. 다음 단계를 제공된 순서대로 따르는 것이 중요합니다.

  1. openthread/src/cli 디렉터리에서 연결된 Cmd를 찾습니다. 예를 들어 ba state을 찾으려면 Cmd("ba")를 검색합니다. 각 명령어에는 연결된 함수 템플릿이 있습니다.

    template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])

  2. 함수 템플릿에서 올바른 명령어 로직을 찾습니다. 예를 들어 ba state의 경우 다음과 같은 결과가 표시됩니다.

    else if (aArgs[0] == "state")

  3. 로직이 시작되기 전에 @cli Doxygen 블록을 시작합니다.

    /**
 * @cli ba state

  4. 다음으로, @cli 바로 아래에 @code를 사용하여 예시를 추가합니다. 예를 하나 이상 포함하세요. > 프롬프트를 포함하지 말고 표준 Done 응답을 포함하여 전체 반환 출력을 문서화해야 합니다.

     * @code
 * ba state
 * Started
 * Done
 * @endcode

CLI 명령어는 일반적인 API 메서드 및 함수에 대한 명령줄 액세스를 제공하므로 일부 명령어는 해당 API와 동일한 설명을 공유합니다. 명령어 설명이 동일하면 다음 단계를 완료합니다.

  1. openthread/include/openthread 디렉터리에서 연결된 API를 찾습니다. 예를 들어 ba state는 otBorderAgentGetState에 매핑됩니다.

  2. api_copy 명령어를 사용한 다음 바로 아래에 API 이름을 입력합니다. API 정의 앞에 파운드 기호 #를 사용하여 자동 Doxygen 링크를 만들어야 합니다.

    @par api_copy
#otBorderAgentGetState

다음은 OT CLI 명령어를 자동으로 생성하는 데 필요한 최소 Doxygen 주석의 전체 예입니다.

/**
 * @cli ba state
 * @code
 * ba state
 * Started
 * Done
 * @endcode
 * @par api_copy
 * #otBorderAgentGetState
 */

HTML 출력을 검토하려면 ba state를 참고하세요. 고급 예와 추가 옵션은 다음 섹션을 참고하세요.

CLI 템플릿 옵션

CLI 명령어는 ALIAS 태그 @cli로 시작하는 하나의 연속 주석 블록으로 그룹화됩니다. 여러 @code 예가 지원됩니다.

각 태그에 지정하는 순서가 중요합니다.

  • @cparam은(는) @code 이후여야 합니다.
  • API 설명을 복사하는 경우 @par api_copy가 @cparam 뒤에 와야 합니다.
 * @cli command name (overload1,overload2)
 * @code
 * command name arg1
 * Done
 * @endcode
 * @cparam command name @ca{arg1} [@ca{opt-arg}] [@ca{choose-1}|@ca{choose-2}]
 * Optional parameter description; displays below the Parameter heading.
 * *   Markdown and lists are supported.
 * @par api_copy
 * #{apiName}
 * @par
 * Optional CLI specific paragraph. Markdown and lists are supported.
 * @note Notes are supported.
 * @csa{other command name}
 * @sa API method or function name

다음으로 각 ALIAS 태그가 사용되는 방식을 자세히 알아봅니다.

명령어 이름

@cli 다음에 오는 모든 텍스트는 명령어 이름 헤더가 됩니다. 이 헤더는 동적 연결에 사용됩니다(예: netdata publishprefix 명령어).

 * @cli netdata publish prefix

다른 명령어는 더 복잡할 수 있습니다. 예를 들어 netdata publish dnssrp unicast는 몇 가지 옵션을 제공합니다.

  1. 주소 및 포트 번호로 게시
  2. 포트 번호 및 기기의 메시-로컬 EID로 게시

명령어가 오버로드된 경우 괄호를 사용하여 명령어를 고유하게 식별합니다.

 * @cli netdata publish dnssrp unicast (mle)
 * @cli netdata publish dnssrp unicast (addr,port)

명령어 설명

명령어 설명을 문서화하는 방법에는 세 가지가 있습니다. API 설명을 복사하거나, API 설명을 사용하되 정보를 더 추가하거나, CLI 명령어에만 속하는 완전히 고유한 설명을 제공할 수 있습니다. 다음 섹션에서는 각 방법을 살펴보겠습니다.

해당 API 설명을 복사합니다.

api_copy를 사용하여 해당 API 메서드 또는 함수를 복사합니다. API를 복사할 때 설명이 API와 CLI 명령어에 모두 적용되어야 합니다. 함수에만 적용되는 구문(예: This function 또는 This method)은 사용하지 마세요. 능동태(예: Gets the 또는 Sets the)를 사용하는 것이 좋습니다.

 * @par api_copy
 * #otBorderAgentGetState

API 설명에 더 많은 정보 추가

api_copy를 사용하지만 CLI 명령어에만 적용되는 정보를 추가해야 하는 경우 @par를 사용합니다. @par 태그 뒤에는 다음 줄로 드롭다운해야 합니다.

 * @par api_copy
 * #otBorderAgentGetState
 * @par
 * CLI description here; add a few things that do not apply to the API method.
 * @par
 * Start a new paragraph.

이러한 단락은 API 설명 다음에 표시됩니다.

CLI 관련 설명만 제공합니다.

일부 CLI 명령어는 여러 API를 사용하거나 API 호출과 다릅니다. 연결된 API가 없는 앱도 있습니다(예: netdata help). 별도의 설명을 제공하려면 @par를 사용합니다. @par 제목은 포함하지 말고 다음 줄에서 설명을 시작하세요. 이 시나리오에서는 @api_copy를 사용하지 마세요.

/**
 * @cli netdata help
 * @code
 * netdata help
 * ...
 * show
 * steeringdata
 * unpublish
 * Done
 * @endcode
 * @par
 * Gets a list of `netdata` CLI commands.
 */

매개변수

@cparam 및 @ca를 사용하여 명령어 매개변수를 정의합니다.

  • 선택적 인수를 대괄호 [ ]로 묶습니다.
  • 인수 선택 항목 사이에는 세로 막대 | (파이프)를 사용합니다.
  • 매개변수 세부정보를 표시하려면 @cparam 태그 아래에 문장 및 마크다운 목록을 입력하면 됩니다.

세부정보가 포함된 매개변수

 * @cparam netdata publish prefix @ca{prefix} [@ca{padcrosnD}] [@ca{high}|@ca{med}|@ca{low}]
 * OT CLI uses mapped arguments to configure #otBorderRouterConfig values. @moreinfo{the @overview}.

HTML 출력을 검토하려면 netdata 게시 프리픽스를 참고하세요.

마크다운 목록이 있는 매개변수

@cparam 뒤에 목록을 사용할 수도 있습니다. 이는 사용되는 명령어 인수에 관한 세부정보를 제공하려는 경우에 유용합니다.

 * @cparam netdata show [@ca{local}] [@ca{-x}]
 * *   The optional `-x` argument gets Network Data as hex-encoded TLVs.
 * *   The optional `local` argument gets local Network Data to sync with Leader.

HTML 출력을 검토하려면 netdata Show를 참고하세요.

@cli 블록은 공백 없이 하나의 연속된 댓글이어야 합니다. @cparam 아래에 목록을 추가한 후 목록 아래에 다른 단락이 필요하면 마침표 .를 사용하여 수동으로 목록을 종료합니다.

* @cparam commandname [@ca{qmr}]
* [`q`, `m`, and `r`] map to #otLinkMetricsValues.
* *   `q`: Layer 2 LQI (#otLinkMetricsValues::mLqiValue).
* *   `m`: Link Margin (#otLinkMetricsValues::mLinkMarginValue).
* *   `r`: RSSI (#otLinkMetricsValues::mRssiValue).
* .
* Add another paragraph here. The dot above will end the HTML list that's generated.
* This paragraph displays under the Parameters heading, and not the command description.

추가 예는 Doxygen의 목록을 참고하세요.

#otFunctionName 또는 @sa로 다른 API 메서드 또는 함수에 연결할 수 있습니다. CLI 주석 블록 끝에 다음 링크를 입력합니다.

/**
 * @cli netdata publish prefix
 * @code
 * netdata publish prefix fd00:1234:5678::/64 paos med
 * Done
 * @endcode
 * @cparam netdata publish prefix @ca{prefix} [@ca{padcrosnD}] [@ca{high}|@ca{med}|@ca{low}]
 * OT CLI uses mapped arguments to configure #otBorderRouterConfig values. @moreinfo{the @overview}.
 * @par
 * Publish an on-mesh prefix entry. @moreinfo{@netdata}.
 * @sa otNetDataPublishOnMeshPrefix
 */

@sa 링크는 CLI 및 API 참조 제목에 표시됩니다. HTML 출력을 검토하려면 netdata 게시 프리픽스를 참고하세요.

Doxygen은 일반적인 단어를 CLI 클래스 링크(예: Joiner)로 오인할 수 있습니다. Doxygen이 문장에 사용되는 키워드나 클래스 이름에 연결되지 않도록 하려면 단어 앞에 % 연산자를 사용합니다. 예를 들면 다음과 같습니다.

Clear the %Joiner discerner

자세한 내용은 Doxygen 가이드의 자동 링크 생성을 참고하세요.

다른 명령어에 연결하려면 @csa를 사용합니다.

* @csa{netdata publish dnssrp anycast}

명령어가 오버로드된 경우 괄호를 포함하고 해당하는 경우 쉼표를 추가합니다. 괄호 안에는 공백을 사용하지 않습니다.

* @csa{netdata publish dnssrp unicast (addr,port)}
* @csa{netdata publish dnssrp unicast (mle)}

Doxygen 특수 명령어

CLI 명령어는 다음과 같은 Doxygen ALIASES 및 특수 명령어를 지원합니다.

별칭 예 설명
@cli @cli ba 포트 명령어 이름입니다. CLI 주석 블록을 시작합니다.
@코드 @code
ba 포트
41953
완료
@endcode		 명령어 예
@ca [@ca{prefix}] 명령어 인수입니다. 선택적 인수에는 대괄호 [ ]를 사용합니다.
@cparam @cparam Joiner DISerner @ca{discerner}
매개변수 세부정보		 명령어 매개변수.
@par @par
선택적 CLI 설명입니다.		 CLI 관련 단락
@csa @csa{prefix add} 명령어도 참고하세요. 다른 명령어에 연결됩니다.
@sa @sa otBorderRouterConfig 참고 항목 API 참조에 대한 링크를 만듭니다.
@overview @overview OpenThread CLI 개요 링크를 만듭니다.
@넷데이터 @넷데이터 OT CLI로 네트워크 데이터 표시 및 관리 링크를 만듭니다.
@데이터 세트 @데이터 세트 OT CLI로 데이터 세트 표시 및 관리 링크를 만듭니다.
@udp @udp OT CLI로 UDP 기능 테스트 링크를 만듭니다.
@추가 정보 @moreinfo{@netdata} 추천 링크를 만듭니다.
@메모 @note 중요한 설명선입니다. 메모 콜아웃 상자를 만듭니다.

make pretty 스크립트로 인해 손상된 줄 수정

CLI 매개변수 또는 명령어 출력과 같은 일부 코드 주석은 openthread.io 참조에서 올바르게 렌더링되도록 한 줄로 해야 합니다. 그러나 make pretty는 열 너비 제한을 적용하여 긴 줄의 렌더링된 출력이 손상될 수 있습니다.

이 문제는 아래 두 가지 예에서와 같이 줄바꿈을 추가하고 HTML 주석 태그로 묶으면 해결할 수 있습니다.

첫 번째 예는 최대 6개의 매개변수를 사용할 수 있는 dns resolve 명령어입니다. make pretty 검사를 전달하면서 Doxygen을 사용하여 구문을 올바르게 렌더링하려면 매개변수를 소스에서 세 줄로 분할해야 합니다.

* @cparam dns resolve @ca{hostname} [@ca{dns-server-IP}] <!--
* -->                 [@ca{dns-server-port}] [@ca{response-timeout-ms}] <!--
* -->                 [@ca{max-tx-attempts}] [@ca{recursion-desired-boolean}]

두 번째 예는 history ipaddr list 5 명령어의 출력입니다. 출력이 올바르게 렌더링되고 여전히 make pretty 검사를 통과하려면 5개의 출력 줄이 다음과 같이 두 줄로 분할되어야 합니다.

* history ipaddr list 5
* 00:00:20.327 -> event:Removed address:2001:dead:beef:cafe:c4cb:caba:8d55:e30b <!--
* -->prefixlen:64 origin:slaac scope:14 preferred:yes valid:yes rloc:no
* 00:00:59.983 -> event:Added address:2001:dead:beef:cafe:c4cb:caba:8d55:e30b <!--
* -->prefixlen:64 origin:slaac scope:14 preferred:yes valid:yes rloc:no
* 00:01:22.535 -> event:Added address:fd00:0:0:0:0:0:0:1 prefixlen:64 <!--
* -->origin:manual scope:14 preferred:yes valid:yes rloc:no
* 00:02:33.221 -> event:Added address:fdde:ad00:beef:0:0:ff:fe00:fc00 <!--
* -->prefixlen:64 origin:thread scope:3 preferred:no valid:yes rloc:no
* 00:02:33.221 -> event:Added address:fdde:ad00:beef:0:0:ff:fe00:5400 <!--
* -->prefixlen:64 origin:thread scope:3 preferred:no valid:yes rloc:yes
* Done