자바 문서 주석 용법+자바 Doc 사용 설명
문서 주석 은 설명 류,인터페이스,방법,구조 기,구성원 속성 을 책임 집 니 다.JDK 가 제공 하 는 도구 인 javadoc 에서 해석 할 수 있 으 며,프로그램 설명 문 서 를 웹 파일 로 표시 하 는 설명 을 자동 으로 생 성 합 니 다.
메모:문서 설명 은 클래스,인터페이스,방법,구조 기,구성원 필드 앞 에 써 야 합 니 다.다른 위치 에 쓰 면 유효 하지 않 습 니 다.
JavaDoc 공식 설명
How to Write Doc Comments for the Javadoc Tool
클래스 에 적 힌 자바 독
클래스 에 적 힌 문서 표 시 는 일반적으로 세 단락 으로 나 뉜 다.
4.567917.첫 번 째 부분:개요 설명 은 보통 한 마디 또는 한 마디 로 이런 역할 을 간략하게 묘사 하고 영어 마침 표를 끝으로 끝난다4.567917.두 번 째 단락:상세 한 설명 은 보통 한 단락 또는 여러 단락 의 말로 이런 역할 을 상세 하 게 묘사 하 는데 보통 모든 단락 의 말 은 영문 마침 표를 끝으로 끝난다
단일 줄 예제:
package org.springframework.jdbc.core;
/**
* Simple adapter for {@link PreparedStatementSetter} that applies a given array of arguments.
*
*/
public class ArgumentPreparedStatementSetter implements PreparedStatementSetter, ParameterDisposer {
}
여러 줄 예제:
package java.lang;
/**
* The {@code Long} class wraps a value of the primitive type {@code
* long} in an object. An object of type {@code Long} contains a
* single field whose type is {@code long}.
*
* <p> In addition, this class provides several methods for converting
* a {@code long} to a {@code String} and a {@code String} to a {@code
* long}, as well as other constants and methods useful when dealing
* with a {@code long}.
*
* <p>Implementation note: The implementations of the "bit twiddling"
* methods (such as {@link #highestOneBit(long) highestOneBit} and
* {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are
* based on material from Henry S. Warren, Jr.'s <i>Hacker's
* Delight</i>, (Addison Wesley, 2002).
*
* @author Lee Boynton
* @author Arthur van Hoff
* @author Josh Bloch
* @author Joseph D. Darcy
* @since JDK1.0
*/
public final class Long extends Number implements Comparable<Long> {
}
주석 에@으로 시작 하 는 동 동 은 자바 doc 문서 태그 라 고 불 리 며 JDK 가 정의 한@author,@version,@since,@see,@link,@code,@param,@return,@exception,@throws 등 입 니 다.@link:{@link 패키지 이름.클래스 이름\#방법 명(매개 변수 유형)}관련 코드 에 빠르게 연결 하 는 데 사용 합 니 다.
@link 는 문법{@link 패키지 이름 을 사용 합 니 다.클래스 이름\#방법 이름(매개 변수 유형)}을 사용 합 니 다.패키지 이름 이 현재 클래스 에 가 져 왔 을 때 생략 할 수 있 습 니 다.클래스 이름 일 수도 있 고 하나의 방법 이름 일 수도 있 습 니 다.방법 이름 은 이 문서 에 표 시 된 클래스 나 방법 을 사용 합 니 다.Ctrl 키+마 우 스 를 누 르 고 해당 클래스 나 방법 으로 빠르게 이동 할 수 있 습 니 다.html 로 해석 하 는 것 은 사실
패키지 이름 을 사용 하 는 것 입 니 다.클래스 이름\#방법 명(매개 변수 유형)
@link 예제
//
{@link java.nio.charset.CharsetEncoder}
//
{@link String} and {@link StringBuilder}
// ,
{@link #equals(Object)}
// . # ( )
{@link java.lang.Long#toString(long)}
@code:{@codetext}텍스트 를 code 로 표시 합 니 다.@code 의 사용 문법{@codetext}은
text
로 해 석 됩 니 다.텍스트 를 코드 스타일 로 표시 하 는 텍스트 는 code 내부 에서<,>등 html 태그 로 해석 되 지 않 습 니 다.code 라벨 은 자신의 스타일 이 있 습 니 다.
일반적으로 자바 doc 에 서 는 클래스 이름 이나 방법 명 만 언급 되면@code 로 표시 해 야 합 니 다.
2 단:상세 설명
상세 한 설명 은 보통 한 단락 또는 여러 단락 으로 클래스 의 역할 을 상세 하 게 설명 합 니 다.상세 한 설명 에 서 는 html 라벨 을 사용 할 수 있 습 니 다.예 를 들 어
,
,,
- ,등 라벨 은 단락 p 라벨 로 시작 합 니 다.
- 기본 클래스 의 문서 주석 이 하위 클래스 로 계승 되 었 습 니 다
- 하위 클래스 는 자신의 주석(특수 화 확장)을 추가 할 수 있 습 니 다 @return@param@throws 도 계승 된다예시
상세 한 설명 과 개요 설명 중간 에 보통 빈 줄 로 나 누 어 집 니 다.인 스 턴 스 는 다음 과 같 습 니 다.
package org.springframework.util;
/**
* Miscellaneous {@link String} utility methods.
*
* <p>Mainly for internal use within the framework; consider
* <a href="http://commons.apache.org/proper/commons-lang/" rel="external nofollow" rel="external nofollow" >Apache's Commons Lang</a>
* for a more comprehensive suite of {@code String} utilities.
*
* <p>This class delivers some simple functionality that should really be
* provided by the core Java {@link String} and {@link StringBuilder}
* classes. It also provides easy-to-use methods to convert between
* delimited strings, such as CSV strings, and collections and arrays.
*
* @author Rod Johnson
* @author Juergen Hoeller
* @author Keith Donald
* @author Rob Harrop
* @author Rick Evans
* @author Arjen Poutsma
* @author Sam Brannen
* @author Brian Clozel
* @since 16 April 2001
*/
public abstract class StringUtils {}
일반 단락 은 p 태그 로 표시 합 니 다.클래스 이름과 방법 명 은 모두@code 로 표시 합 니 다.조직 과 관련 된 경우 보통 a 태그 로 링크 주 소 를 제공 합 니 다.@param
일반 클래스 에서 범 형 을 지원 할 때@param 을 통 해 범 형의 유형 을 설명 합 니 다.
package java.util;
/**
* @param <E> the type of elements in this list
*
*/
public interface List<E> extends Collection<E> {}
@author자세 한 설명 은 일반적으로@author 를 사용 하여 작성 자 를 표시 합 니 다.한 파일 에 여러 개의 작성 자가 있 으 면 여러 개의@author 를 표시 합 니 다.@author 뒤 에는 작성 자의 이름(메 일 주소 도 첨부 할 수 있 습 니 다),조직 이름(조직 홈 페이지 주소 도 첨부 할 수 있 습 니 다)을 표시 할 수 있 습 니 다.
//
@author Rod Johnson
// ,
@author Igor Hersht, [email protected]
//
@author <a href="mailto:[email protected]" rel="external nofollow" >Ovidiu Predescu</a>
//
@author [email protected]
//
@author Apache Software Foundation
//
@author <a href="https://jakarta.apache.org/turbine" rel="external nofollow" > Apache Jakarta Turbine</a>
@see 참조@see 는 일반적으로 이 클래스 와 연 결 된 클래스 를 표시 하 는 데 사 용 됩 니 다.@see 는 클래스 에 도 사용 할 수 있 고 방법 에 도 사용 할 수 있 습 니 다.
/**
* @see IntStream
* @see LongStream
* @see DoubleStream
* @see <a href="package-summary.html" rel="external nofollow" >java.util.stream</a>
* /
public interface Stream<T> extends BaseStream<T, Stream<T>> {}
@since 다음 버 전부터@since 는 일반적으로 파일 생 성 시 프로젝트 에 대응 하 는 버 전 을 표시 하 는 데 사 용 됩 니 다.일반적으로 버 전 번호 와 같은 시간 으로 파일 이 현재 생 성 된 시간 을 표시 할 수 있 습 니 다.
package java.util.stream;
/**
* @since 1.8
*/
public interface Stream<T> extends BaseStream<T, Stream<T>> {}
package org.springframework.util;
/**
* @since 16 April 2001
*/
public abstract class StringUtils {}
@version 버 전@version 은 현재 버 전 을 표시 하 는 데 사 용 됩 니 다.기본 값 은 1.0 입 니 다.
package com.sun.org.apache.xml.internal.resolver;
/**
* @version 1.0
*/
public class CatalogManager {}
방법 에 적 힌 자바 독.방법 에 적 힌 문서 표 시 는 일반적으로 세 단락 으로 나 뉜 다.
4.567917.첫 번 째 단락:개요 설명 은 보통 한 마디 또는 한 마디 로 이 방법의 역할 을 간략하게 묘사 하고 영어 마침 표를 끝으로 끝난다4.567917.두 번 째 단락:상세 한 설명 은 보통 한 단락 또는 여러 단락 의 말로 이 방법의 역할 을 상세 하 게 묘사 하 는데 보통 모든 단락 의 말 은 영문 마침 표를 끝으로 끝난다4.567917.세 번 째 단계:문서 표시,매개 변수 표시,반환 값,이상,참조 등 4.567918.
방법 에 대한 상세 한 설명 에 있어 html 라벨 을 자주 사용 합 니 다.보통 p 라벨 로 시작 합 니 다.그리고 p 라벨 은 보통 단일 라벨 로 끝 라벨 을 사용 하지 않 습 니 다.그 중에서 가장 많이 사용 하 는 것 은 p 라벨 과 pre 라벨,ul 라벨,i 라벨 입 니 다.
pre 탭 은 미리 포맷 된 텍스트 를 정의 할 수 있 습 니 다.pre 탭 에 포 위 된 텍스트 는 보통 빈 칸 과 줄 바 꿈 자 를 유지 합 니 다.텍스트 도 등 폭 글꼴 로 나타 납 니 다.pre 태그 의 흔 한 응용 프로그램 은 컴퓨터 의 소스 코드 를 나타 내 는 것 입 니 다.
일반 p 는 pre 와 자주 결합 하여 사용 하거나 pre 와@code 를 결합 하여 공동으로 사용 합 니 다(@code 방식 을 추천 합 니 다)
일반적으로 pre 를 사용 하여 방법 을 예 로 들 면
메모:pre 태그 에 번호 보다 작 거나 큰 번호 가 있 으 면,예 를 들 어 범 형 이 자바 doc 를 생산 할 때 오류 가 발생 할 수 있 습 니 다.
p 결합 pre 사용
/**
* Check that the given {@code CharSequence} is neither {@code null} nor
* of length 0.
* <p>Note: this method returns {@code true} for a {@code CharSequence}
* that purely consists of whitespace.
* <p><pre class="code">
* StringUtils.hasLength(null) = false
* StringUtils.hasLength("") = false
* StringUtils.hasLength(" ") = true
* StringUtils.hasLength("Hello") = true
* </pre>
* @param str the {@code CharSequence} to check (may be {@code null})
* @return {@code true} if the {@code CharSequence} is not {@code null} and has length
* @see #hasText(String)
*/
public static boolean hasLength(@Nullable CharSequence str) {
return (str != null && str.length() > 0);
}
pre 결합@code 사용
<pre>{@code
Person[] men = people.stream()
.filter(p -> p.getGender() == MALE)
.toArray(Person[]::new);
}</pre>
@param@param 뒤에 매개 변수 이름과 매개 변수 설명
/**
* @param str the {@code CharSequence} to check (may be {@code null})
*/
public static boolean hasText(@Nullable CharSequence str) {
return (str != null && str.length() > 0 && containsText(str));
}
@return@return 과 반환 값 에 대한 설명
/**
* @return {@code true} if the {@code CharSequence} is not {@code null},
* its length is greater than 0, and it does not contain whitespace only
*/
public static boolean hasText(@Nullable CharSequence str) {
return (str != null && str.length() > 0 && containsText(str));
}
@throws@throws 와 이상 유형 이상 설명,설명 방법 내부 에서 던 질 수 있 는 이상
/**
* @throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset) {}
@exception@exception 은 throws 에 대응 하 는 이상 을 설명 하 는 데 사 용 됩 니 다.
package com.sun.jmx.remote.security;
/**
* @exception LoginException if the logout fails.
*/
public boolean logout() throws LoginException {}
@deprecated@deprecated 는 클래스 나 구성원 이 만 료 되 었 음 을 표시 하 는 데 사 용 됩 니 다.{@link}에 맞 춰 사용 합 니 다.
/**
* @deprecated as of 5.0.4, in favor of {@link Locale#toLanguageTag()}
*/
@Deprecated
public static String toLanguageTag(Locale locale) {
return locale.getLanguage() + (hasText(locale.getCountry()) ? "-" + locale.getCountry() : "");
}
@see@see 는 클래스 에 도 사용 할 수 있 고 방법 에 도 사용 할 수 있 으 며 참고 할 수 있 는 클래스 나 방법 을 표시 합 니 다.
/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset) {}
@value{@value}상수 값 을 표시 하 는 데 사용 합 니 다.
/** {@value} */
private static final Integer QUANTITY = 1;
@inheritDoc@inheritDoc 은 재 작성 방법 이나 하위 클래스 에 주석 을 달 고 부모 클래스 의 자바 doc 를 계승 하 는 데 사 용 됩 니 다.
4
spring-core 의 StringUtils 예제
package org.springframework.util;
/**
* Miscellaneous {@link String} utility methods.
*
* <p>Mainly for internal use within the framework; consider
* <a href="http://commons.apache.org/proper/commons-lang/" rel="external nofollow" rel="external nofollow" >Apache's Commons Lang</a>
* for a more comprehensive suite of {@code String} utilities.
*
* <p>This class delivers some simple functionality that should really be
* provided by the core Java {@link String} and {@link StringBuilder}
* classes. It also provides easy-to-use methods to convert between
* delimited strings, such as CSV strings, and collections and arrays.
*
* @author Rod Johnson
* @author Juergen Hoeller
* @author Keith Donald
* @author Rob Harrop
* @author Rick Evans
* @author Arjen Poutsma
* @author Sam Brannen
* @author Brian Clozel
* @since 16 April 2001
*/
public abstract class StringUtils {
/**
* Check that the given {@code CharSequence} is neither {@code null} nor
* of length 0.
* <p>Note: this method returns {@code true} for a {@code CharSequence}
* that purely consists of whitespace.
* <p><pre class="code">
* StringUtils.hasLength(null) = false
* StringUtils.hasLength("") = false
* StringUtils.hasLength(" ") = true
* StringUtils.hasLength("Hello") = true
* </pre>
* @param str the {@code CharSequence} to check (may be {@code null})
* @return {@code true} if the {@code CharSequence} is not {@code null} and has length
* @see #hasText(String)
*/
public static boolean hasLength(@Nullable CharSequence str) {
return (str != null && str.length() > 0);
}
}
몸소 실천 하 다
package com.example.javadocdemo;
import java.math.BigDecimal;
import java.util.Objects;
/**
* {@code OrderService} .
*
* <p> 、 、
*
* @see Order
* @author <a href="mailto:[email protected]" rel="external nofollow" >Lerry Li</a>
* @since 2019/05/06
*/
public class OrderService {
/** {@value} */
private static final Integer QUANTITY = 1;
/**
* .
*
* <p> id ( id ).
*
* <pre>{@code
*
* List<Goods> items = new ArrayList<>();
* Goods goods = new Goods(1L, BigDecimal.ONE);
* Goods goods2 = new Goods(2L, BigDecimal.TEN);
* items.add(goods);
* items.add(goods2);
*
* Order order1 = new Order();
* order.setUserId("1");
* order.setItems(items);
* OrderService#createOrder(order);
* }
* </pre>
*
* @param order
* @throws NullPointerException
* @exception IllegalArgumentException
* @return
* @version 1.0
* @see Order
*/
public boolean createOrder(Order order) throws IllegalArgumentException{
Objects.requireNonNull(order);
List<Goods> items = order.getItems();
items.forEach(goods -> {
BigDecimal quantity = goods.getQuantity();
if (quantity == null || BigDecimal.ZERO.compareTo(quantity) == 0) {
throw new IllegalArgumentException();
}
});
System.out.println("create order...");
return true;
}
}
자바 독 생 성IDEA 를 통 해 Javadoc:Tools C>Generate Javadoc 생 성
인 코딩 을 설정 해 야 합 니 다.설정 하지 않 으 면 생 성 되 는 JavaDoc 은 인 코딩 이 흐 트 러 지고 Output directory 도 설정 해 야 합 니 다.
여기에 몇 가지 특별히 주의해 야 할 점 이 있다.
1.IDEA 의 자바 독 생 성 기능 은 메뉴 Tools->Generate 자바 독 항목 에 있 습 니 다.
2.상기 메뉴 항목 을 클릭 하면 자바 독 생 성 대화 상자 가 나타 납 니 다.일반적인 옵션 은 직관 적 이 므 로 자세히 말 할 필요 가 없습니다.그러나 자바 독 을 생 성 하 는 소스 코드 대상 의 선택 에 주의해 야 한다.일반적으로 모듈(Module)을 위주 로 하고 필요 할 때 필요 한 자바 소스 코드 파일 을 따로 선택 할 수 있 으 며 Project 를 자바 독 으로 생 성 하 는 소스 범 위 를 추천 하지 않 는 다.
3.그 안에 Locale 이 선택 할 수 있 는 항목 이 있 습 니 다.생 성 해 야 하 는 자바 Doc 이 어떤 언어 버 전 으로 보 여 주 는 지 를 나타 내 는 것 입 니 다.자바 doc.exe 의 도움 설명 에 따 르 면 이것 은 자바 doc.exe 의-locale 매개 변수 입 니 다.채 우지 않 으 면 기본 값 은 영어 또는 현재 운영 체제 의 언어 일 수 있 습 니 다.국민 인 이상 zh 를 작성 하 는 것 을 권장 합 니 다.CN,이렇게 생 성 된 자바 독 은 중국어 버 전 입 니 다.물론 자바 독 의 프레임 워 크 에서 통용 되 는 고정 디 스 플레이 영역 은 모두 중국어 입 니 다.당신 이 작성 한 주석 변환 내용 은 당신 이 설명 한 내용 에 근거 합 니까?
4.또 하나의"Other command line arguments:"선택 할 수 있 는 항목 이 있 습 니 다.매우 중요 합 니 다.자바 doc.exe 에 직접 전달 하 는 매개 변수 내용 을 작성 하 는 것 입 니 다.중요 한 설정 이 있 기 때문에 자바 doc.exe 에 직접 매개 변수 형식 으로 만 전달 할 수 있 습 니 다.여기에 다음 과 같은 인 자 를 입력 해 야 합 니 다.
-encoding UTF-8-charset UTF-8-windows title"JavaDoc 사용 설명"-linkhttps://docs.oracle.com/javase/8/docs/api
5.첫 번 째 매개 변수-encoding UTF-8 은 원본 코드(자바 Doc 표준 에 부합 되 는 주석 포함)는 UTF-8 인 코딩 을 바탕 으로 처리 과정 에서 중국어 등 비 영어 문자 의 난호 가 발생 하지 않도록 합 니 다.두 번 째 인자-charset UTF-8 은 자바 Doc 하이퍼텍스트 를 처리 하고 생 성 할 때 사용 하 는 문자 집합 도 UTF-8 을 인 코딩 으로 하고 있 으 며,현재 모든 브 라 우 저 는 UTF-8 을 지원 합 니 다.이렇게 하면 가장 통용 되 고 중국 어 를 지원 하 는 것 이 좋 습 니 다.세 번 째 인자-windows title 은 생 성 된 자바 Doc 하이퍼텍스트 가 브 라 우 저 에서 열 렸 을 때 브 라 우 저 창 제목 표시 줄 에 표 시 된 텍스트 내용 을 표시 합 니 다.네 번 째 매개 변수-link 는 매우 중요 합 니 다.이것 은 당신 이 생 성 한 자바 Doc 에서 다른 외부 자바 류 에 대한 인용 이 많이 포함 되 어 있 음 을 나타 냅 니 다.전체 한정 이름 을 사용 하 시 겠 습 니까?하이퍼링크 가 있 는 짧 은 이름 을 사용 하 시 겠 습 니까?
예 를 들 어 저 는 Public void func(String arg)방법 을 만 들 었 습 니 다.이 방법 은 자바 Doc 을 생 성 할 때-link 인 자 를 지정 하지 않 으 면 자바 Doc 에서 이 방법 에 대한 표현 은 자동 으로 Public void func(java.lang.string arg)로 변 합 니 다.String 이라는 종 류 는 제 가 실현 하 는 클래스 에 있어 외부 참조 클래스 이기 때 문 입 니 다.자바 표준 라 이브 러 리 의 클래스 이지 만.-linkhttps://docs.oracle.com/javase/8/docs/api/인 자 를 지정 하면 자바 doc.exe 는 자바 Doc 을 생 성 할 때 전체 한정 이름 인 자바.lang.String 이 아 닌 String 이라는 짧 은 이름 을 사용 합 니 다.또한 String 의 짧 은 이름 에 하이퍼링크 를 자동 으로 생 성하 여 공식 자바 SE 표준 문서https://docs.oracle.com/javase/8/docs/api/에서 String 류 에 대한 상세 한 문서 주 소 를 가 리 킵 니 다.
-link 는 실질 적 으로 자바 doc.exe 가 제공 하 는 외부 인용 류 의 자바 Doc 주소 에 따라 package-list 라 는 텍스트 파일 을 찾 는 것 을 알려 줍 니 다.이 텍스트 파일 에는 모든 외부 인용 류 의 전체 한정 이름 이 포함 되 어 있 기 때문에 생 성 된 새로운 자바 Doc 은 외부 인용 류 의 전체 제한 이름 을 사용 하지 않 고 짧 은 이름 만 사용 해 야 합 니 다.외부 에서 자바 Doc 을 참조 하 는 자세 한 문서 하이퍼링크 를 자동 으로 만 들 수 있 습 니 다.
모든 자바 독 은 루트 디 렉 터 리 아래 패키지-list 파일 이 있 습 니 다.우리 가 만 든 자바 독 을 포함 합 니 다.
성과 보기
설정 이 끝 난 후 OK 단 추 를 누 르 면 console 에서 다음 로그 출력 을 보면 자바 독 생 성 성공 을 설명 합 니 다.
자바 독 생 성 이 완료 되면 루트 디 렉 터 리 에서 index.html 파일 을 찾 을 수 있 습 니 다.이 파일 을 열 면 우리 의 표준 자바 독 API 문 서 를 볼 수 있 습 니 다.
이상 은 개인 적 인 경험 이 므 로 여러분 에 게 참고 가 되 기 를 바 랍 니 다.여러분 들 도 저 희 를 많이 응원 해 주시 기 바 랍 니 다.
이 내용에 흥미가 있습니까?
현재 기사가 여러분의 문제를 해결하지 못하는 경우 AI 엔진은 머신러닝 분석(스마트 모델이 방금 만들어져 부정확한 경우가 있을 수 있음)을 통해 가장 유사한 기사를 추천합니다:
JPA + QueryDSL 계층형 댓글, 대댓글 구현(2)이번엔 전편에 이어서 계층형 댓글, 대댓글을 다시 리팩토링해볼 예정이다. 이전 게시글에서는 계층형 댓글, 대댓글을 구현은 되었지만 N+1 문제가 있었다. 이번에는 그 N+1 문제를 해결해 볼 것이다. 위의 로직은 이...
텍스트를 자유롭게 공유하거나 복사할 수 있습니다.하지만 이 문서의 URL은 참조 URL로 남겨 두십시오.
CC BY-SA 2.5, CC BY-SA 3.0 및 CC BY-SA 4.0에 따라 라이센스가 부여됩니다.