Javadoc에서 Markdown 문법 사용하기

2024년 JDK 23이 출시되면서 JEP-467 로 자바독에 Markdown이 들어왔다.
기존 자바독 방식은 /* */에 HTML 태그를 집어넣어서 문서화할 수 있었는데, 이러면 테이블 쓸 때마다 한세월이라 Ascii Tables 사이트를 애용했었다.

당연히 Intellij IDEA에도 해당 기능이 들어왔지만 Youtrack 링크 그동안 사용법을 몰라 사용하지 못하고 있다가 JEP를 읽고 사용법을 드디어 알았다
다들 JEP를 바로 읽는지 국내에는 별다른 자료가 없어 간단히 소개한다

문법 기준

기본적으로 CommonMarkdown의 스펙을 따른다
간단히 말해서 Github markdown 문법과 유사하게 동작한다고 생각하면 된다. 자세한 사항은 다음 링크를 참조하자.
GFM 서식 설명 문서
GFM spec

주의사항

• Markdown javadoc을 사용하고 싶다면 기존의 /**/ 방식이 아닌 /// 로 시작
• Javadoc의 @param, @return 등 특수 태그는 그대로 사용 가능
• 링크 태그 [] 로 java package를 지정 가능
• ```css 등 인라인 구문을 사용 가능하다
• @param 등 javadoc specific한 태그를 사용한 후에는 마크다운이 제대로 동작하지 않을 수 있다 Intellij idea 버그일 수도 있다.

JEP에 예시 사진으로 첨부된 구문을 보면 더욱 이해하기 쉽다.