unintended_html_in_doc_comment 진단: 주석 안 꺾쇠 괄호가 HTML로 해석될 때
unintended_html_in_doc_comment 진단: 주석 안 꺾쇠 괄호가 HTML로 해석될 때
분석기가 내보내는 진단에는 이름이 있어요. unintended_html_in_doc_comment는 문서 주석(doc comment) 안에 꺾쇠 괄호(<...>)로 감싼 텍스트가 들어 있을 때 Dart 분석기가 알려주는 진단이에요. 이런 텍스트는 markdown에서 HTML 태그로 해석되는데, 보통은 그런 의도가 아닐 때가 많아요.
본문
설명
분석기는 문서 주석에 허용된 예외가 아닌 꺾쇠 괄호로 감싼 텍스트(<...>)가 들어 있을 때 이 진단을 만들어요.
이런 텍스트는 markdown에 의해 HTML 태그로 해석되는데, 보통 의도한 것과 다를 때가 많아요.
허용되는 예외 목록은 린트 규칙 설명에서 확인할 수 있어요.
예시
다음 코드는 문서 주석에 허용된 예외가 아닌 <int> 텍스트가 들어 있어서 이 진단을 만들어요.
/// Converts a List<int> to a comma-separated String.
String f(List<int> l) => '';
흔한 해결 방법
그 텍스트가 코드 스팬(code span)으로 쓰려던 의도였다면, 코드 주변을 백틱(backtick)으로 감싸요.
/// Converts a `List<int>` to a comma-separated String.
String f(List<int> l) => '';
그 텍스트가 링크의 일부로 쓰려던 의도였다면, 코드 주변을 대괄호로 감싸요.
/// Converts a [List<int>] to a comma-separated String.
String f(List<int> l) => '';
꺾쇠 괄호를 포함해 그 텍스트를 있는 그대로 출력하려는 의도라면, 꺾쇠 괄호 앞에 백슬래시 이스케이프(backslash escape)를 붙여요.
/// Converts a List\<int\> to a comma-separated String.
String f(List<int> l) => '';