CLI 명령어는 openthread GitHub 저장소의 CLI 소스 파일에서 생성됩니다.
이 가이드에서는 명령어 목록을 만드는 데 사용하는 커스텀 Doxygen 주석을 사용하는 방법을 안내합니다.
시작하기
CLI 명령어를 문서화하려면 다음 단계를 완료하세요. 다음 단계를 제공된 순서대로 따르는 것이 중요합니다.
openthread/src/cli
디렉터리에서 연결된Cmd
를 찾습니다. 예를 들어ba state
을 찾으려면Cmd("ba")
를 검색합니다. 각 명령어에는 연결된 함수 템플릿이 있습니다.template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
함수 템플릿에서 올바른 명령어 로직을 찾습니다. 예를 들어
ba state
의 경우 다음과 같은 결과가 표시됩니다.else if (aArgs[0] == "state")
로직이 시작되기 전에
@cli
Doxygen 블록을 시작합니다./** * @cli ba state
다음으로,
@cli
바로 아래에@code
를 사용하여 예시를 추가합니다. 예를 하나 이상 포함하세요.>
프롬프트를 포함하지 말고 표준Done
응답을 포함하여 전체 반환 출력을 문서화해야 합니다.* @code * ba state * Started * Done * @endcode
CLI 명령어는 일반적인 API 메서드 및 함수에 대한 명령줄 액세스를 제공하므로 일부 명령어는 해당 API와 동일한 설명을 공유합니다. 명령어 설명이 동일하면 다음 단계를 완료합니다.
openthread/include/openthread
디렉터리에서 연결된 API를 찾습니다. 예를 들어ba state
는otBorderAgentGetState
에 매핑됩니다.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
는 몇 가지 옵션을 제공합니다.
- 주소 및 포트 번호로 게시
- 포트 번호 및 기기의 메시-로컬 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의 목록을 참고하세요.
API 자동 연결
#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