OT CLI 명령어 업데이트

<ph type="x-smartling-placeholder"></ph> GitHub에서 소스 보기

CLI 명령어를 생성하여 Cloud Shell의 CLI 소스 파일에서 openthread GitHub 저장소

이 가이드에서는 맞춤 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 명령어를 자동으로 생성합니다

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

HTML 출력을 검토하려면 다음을 참조하세요. ba state에 대해 자세히 알아보세요. 고급 예시 및 추가 옵션은 다음 섹션을 참고하세요.

CLI 템플릿 옵션

CLI 명령어는 별칭 @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 게시 프리픽스 명령어:

 * @cli netdata publish prefix
드림 <ph type="x-smartling-placeholder">
</ph>

다른 명령어는 더 복잡할 수 있습니다. 예를 들어 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가 없는 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 블록은 공백 없이 연속하는 댓글 1개여야 합니다. @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입니다. 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 별칭과 특수 명령어를 지원합니다.

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

make pretty 스크립트에 의해 손상된 줄 수정

CLI 매개변수 또는 명령어 출력과 같은 일부 코드 주석을 사용 설정해야 합니다. openthread.io 참조에서 올바르게 렌더링되도록 한 줄을 추가합니다. 그러나 make pretty는 열 너비 제한을 적용하며 이로 인해 렌더링된 출력됩니다.

이 상황은 줄바꿈을 추가하고 둘러싸는 방식으로 해결할 수 있습니다. 을 HTML 주석 태그로 대체합니다.

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

* @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