번역: Javadoc 주석에 Markdown 구문 사용

Javadoc 주석에 마크다운 구문 사용

이번 포스팅에서는 표준 Javadoc 구문 대신 Markdown을 사용하여 Javadoc 주석을 작성하는 방법을 살펴보겠습니다 . 그렇다면 마크다운이란 무엇일까요? 마크다운은 동일한 이름의 도구를 사용하여 선택적으로 HTML로 번역할 수 있는 간단한 마크업 언어입니다. Markdown은 포럼 게시물을 작성할 때 readme 파일의 형식을 지정하고 텍스트 편집기에서 아름다운 텍스트 문서를 빠르게 만드는 데 널리 사용됩니다. (Wikipedia: Markdown ) Markdown 형식의 텍스트는 읽기가 매우 쉽습니다. 다양한 종류의 Markdown이 Stack Overflow 또는 GitHub에서 사용자 생성 콘텐츠의 형식을 지정하는 데 사용됩니다.

설치

기본적으로 Javadoc 도구는 Javadoc 주석을 사용하여 API 문서를 HTML로 생성합니다. 이 프로세스는 Doclet을 사용하여 재구성할 수 있습니다 . Doclet은 Javadoc 도구 출력 파일의 콘텐츠와 형식을 지정하는 Java 프로그램입니다. Markdown-doclet은 표준 Java Doclet을 대체하므로 개발자가 Javadoc 주석에 Markdown 구문을 사용할 수 있는 기능을 제공합니다. maven-javadoc-plugin을 사용하여 Maven에 설치할 수 있습니다 . maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

마크다운으로 댓글 작성하기

이제 Markdown 구문을 사용하여 Javadoc 주석을 작성할 수 있습니다. /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } 실행 후

mvn javadoc:Javadoc

생성된 HTML API 문서는 다음 위치에 있습니다.

대상/사이트/apidocs.

위 코드에 대해 생성된 문서는 다음과 같습니다. 그림에서 볼 수 있듯이 Javadoc 주석은 HTML로 완벽하게 변환됩니다.

결론

Markdown은 표준 Javadoc 구문에 비해 분명한 장점이 있습니다. 즉, 소스 코드에서 읽기가 훨씬 쉽습니다. java.util.Map의 메소드 주석 중 일부를 살펴보십시오. 그 중 다수는 서식 지정 태그로 가득 차 있으며 추가 도구를 사용하지 않으면 읽기가 어렵습니다. 하지만 Markdown은 표준 Javadoc 구문으로만 작동할 수 있는 도구 및 IDE에 문제를 일으킬 수 있다는 점을 기억해야 합니다. 출처: mscharhag 블로그 프로그래밍 및 Stuff의 JCG 파트너 Michael Scharhag가 작성한 Javadoc 주석에서 Markdown 구문 사용 .