unintended_html_in_doc_comment 진단: doc 주석의 꺾쇠괄호는 HTML로 취급돼요

unintended_html_in_doc_comment 진단: doc 주석의 꺾쇠괄호는 HTML로 취급돼요

unintended_html_in_doc_comment는 doc 주석에서 꺾쇠괄호 <…>로 감싼 텍스트가 HTML로 취급되는 것을 Dart 분석기가 알려주는 린트(lint) 규칙이에요. Markdown 문법 때문에 꺾쇠괄호가 HTML 태그로 해석될 수 있어서 주의가 필요해요.

출처: unintended_html_in_doc_comment

본문

설명

HTML 태그나 링크를 쓰려는 게 아니라면, doc 주석에서 꺾쇠괄호로 감싼 텍스트 <…>는 쓰지 마세요 (DON'T).

Markdown은 코드의 일부로 HTML 태그를 허용해요. 그래서 예를 들어 T<sub>1</sub>처럼 쓸 수 있어요. Markdown은 허용되는 태그를 제한하지 않고, 태그를 출력에 그대로 포함시켜요. 하지만 Dartdoc은 알려진 유효한 HTML 태그만 허용하고, 허용되지 않는 HTML 태그는 출력에서 생략해요. 아래 허용 태그와 지시자 목록에 없는 HTML 태그는 doc 주석에 넣으면 안 돼요.

Markdown은 또한 <https://example.com/page.html>처럼 <...>로만 구분된 URL로 "자동 링크(auto-link)"를 쓸 수 있게 해줘요. 이런 링크는 Dartdoc도 허용해요. <...>로 감싼 텍스트는 스킴(scheme)이 콜론으로 끝나고 글자 두 개 이상으로 시작하는 유효한 절대 URL(예: <mailto:[email protected]>)일 때 자동 링크가 돼요.

그 밖의 <word...>나 </word...> 등장은 대부분 실수일 가능성이 높아서 이 린트가 경고해요. <나 </ 다음에 글자가 오고 뒤에 매칭되는 >가 있는 것, 즉 HTML 태그처럼 보이는 것은 자동 링크가 아니거나 허용된 HTML 태그로 시작하지 않으면 잘못된 HTML 태그로 간주돼요.

이런 실수는 코드 스팬 밖에서 타입 인자를 쓰는 경우에 생길 수 있어요. 예를 들어 The type List<int> is ...에서 <int>가 HTML 태그처럼 보여요. 코드 스팬의 끝 백틱을 빠뜨려도 같은 효과가 생겨요. The type List is ...도 `를 HTML 태그로 취급해요.

들여쓰기로 코드 블록을 만들 때 충분히 들여쓰지 않아도 이런 일이 생겨요. 코드 블록은 주석과 마커를 구분하는 공백 에 더해서 네 칸을 들여써야 해요. 다만 코드 블록에는 들여쓰기보다 트리플 백틱을 쓰는 걸 선호해요.

다음 HTML 지시자는 허용돼요: HTML 주석 <!-- text -->, 처리 명령(processing instruction) <?...?>, CDATA 섹션, 그리고 <[CDATA...]>.

또한 ] 뒤나 [ 또는 ( 앞에 있지 않은 [List<int>] 같은 DartDoc 링크를 허용하고, 다음과 같은 인식된 HTML 태그들을 허용해요: a, abbr, address, area, article, aside, audio, b, bdi, bdo, blockquote, br, button, canvas, caption, cite, code, col, colgroup, data, datalist, dd, del, dfn, div, dl, dt, em, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hr, i, iframe, img, input, ins, kbd, keygen, label, legend, li, link, main, map, mark, meta, meter, nav, noscript, object, ol, optgroup, option, output, p, param, pre, progress, q, s, samp, script, section, select, small, source, span, strong, style, sub, sup, table, tbody, td, template, textarea, tfoot, th, thead, time, title, tr, track, u, ul, var, video, wbr.

좋지 않은 코드 (BAD)

/// The type List<int>.
/// <assignment> -> <variable> = <expression>
///
///    List<int> func() => [];

좋은 코드 (GOOD)

꺾쇠괄호로 쓸 텍스트는 백틱 코드 스팬으로 감싸거나, 자동 링크로 만들어서 int>가 HTML 태그로 해석되지 않게 해요.

/// The type `List<int>`.
/// The type [List<int>]
/// `<assignment> -> <variable> = <expression>`
/// \<assignment\> -> \<variable\> = \<expression\>`
/// <https://example.com/example>
///
///     List<int> func() => [];
///
/// ```
/// List<int> func() => [];
/// ```

규칙 활성화하기

analysis_options.yaml 파일의 linter > rules 아래에 unintended_html_in_doc_comment를 추가해서 활성화할 수 있어요.

linter:
  rules:
    - unintended_html_in_doc_comment

YAML 맵 문법으로 설정하고 있다면 linter > rules 아래에 unintended_html_in_doc_comment: true를 추가해요.

linter:
  rules:
    unintended_html_in_doc_comment: true

더 알아보기