모든 걸 외울 필요는 없어요. 필요할 때 공식 문서에서 찾아 읽는 힘이 진짜 실력이에요. 이 부록은 자바 표준 문서 Javadoc의 구조를 도식으로 해부하고, 메서드 시그니처를 조각조각 뜯어보며, 실전에서 어떻게 검색하고 활용하는지까지 차근차근 익혀요.
자바를 배우다 보면 API, API 문서, Javadoc이라는 말이 계속 나와요. 셋은 서로 다른 것을 가리켜요. 전자제품에 비유하면 한 번에 잡혀요.
String, ArrayList 등)의 사용설명서예요. 그런데 이 설명서는 사람이 따로 쓴 게 아니라, 소스코드 안의 특별한 주석에서 자동으로 만들어져요.
💡 한 줄로: API는 "정해진 사용 창구", API 문서는 "그 창구 사용법 설명서", Javadoc은 "자바 소스 주석에서 자동 생성된 자바 표준 API 문서"예요.
"abc".length()에서 String 클래스의 length() 메서드를 부르는 것, 이게 API를 사용하는 거예요.그럼 이 Javadoc은 대체 어떻게 만들어질까요? 자바 소스코드 안에 /** ... */ 형태로 쓰인 문서 주석(documentation comment)을, javadoc이라는 도구가 읽어서 HTML 웹페이지로 자동 변환해요. 그래서 우리가 보는 오라클 공식 API 문서는 전부 이 방식으로 만들어진 거예요. (아래 그림)
String이든 ArrayList든 Scanner든 똑같은 눈으로 읽을 수 있어요. 이 부록의 목표가 바로 그 "틀"을 익히는 거예요.
String·ArrayList 같은 클래스 페이지는 늘 같은 순서로 구성돼요.클래스 문서 페이지를 처음 열면 정보가 많아 막막해요. 하지만 항상 같은 순서로 배치돼 있어요: 위에서부터 ① 패키지·클래스명 → ② 타입 계층(상속) → ③ 클래스 설명 → ④ Method Summary(요약 표) → ⑤ Method Detail(상세) 순이에요. 검색창과 배지는 그 위에 얹혀 있고요. 아래 목업에서 각 부분이 "무엇을 보는 곳인지" 화살표로 짚어줄게요.
| 구역 | 여기서 무엇을 보나 | 실전 팁 |
|---|---|---|
| ① 패키지·클래스명 | 어느 패키지(java.lang 등)의 무슨 클래스인지 | import할 경로를 알려줘요(단, java.lang은 자동 import) |
| ② 타입 계층 | 어떤 클래스를 상속(extends)·구현(implements)했는지 | 부모의 기능도 물려받아 쓸 수 있다는 힌트 |
| ③ 클래스 설명 | 이 클래스가 무엇이고 언제 쓰는지 개요·예시 | 처음 보는 클래스는 여기부터 읽기 |
| ④ Method Summary | 사용 가능한 메서드 목록(반환타입·이름·한 줄 설명) | 후보를 훑고 이름 클릭 → 상세로 점프 |
| ⑤ Method Detail | 메서드 하나의 정확한 시그니처·파라미터·반환·예외 | 실제로 코드 쓰기 직전에 확인하는 곳 |
| ⑥ Since/Deprecated | @since(도입 버전), Deprecated(폐기 예정) | 버전 호환·대체 API 찾을 때 핵심 |
| ⑦ 검색창 | 클래스·메서드 이름으로 바로 검색 | 모던 Javadoc(Java 9+)엔 상단에 검색창이 있어요 |
ArrayList 페이지에서 equals가 안 보여도, "Methods inherited from …"에 있으면 쓸 수 있어요.Method Detail을 열면 맨 위에 메서드 시그니처(signature) 한 줄이 나와요. 이 한 줄만 정확히 읽어도 "무엇을 넣고, 무엇이 나오고, 언제 터지는지"를 알 수 있어요. 자바를 대표하는 예제 Integer.parseInt로 뜯어볼게요.
public static int parseInt(String s) throws NumberFormatExceptionInteger.parseInt("123")처럼 문자열 하나(String s)를 넣으면 정수(int)를 돌려주는데, 숫자가 아닌 문자열이면 예외(NumberFormatException)가 터진다." 이 한 문장이 시그니처 한 줄에 다 들어 있어요.
valueOf(int i), valueOf(boolean b), valueOf(char[] data) — 넣는 값의 타입에 따라 알맞은 것이 선택돼요. 문서에서는 내가 넣을 값의 타입과 맞는 줄을 찾으면 돼요.
List<E>, ArrayList<E>처럼 꺾쇠(< >) 안의 글자는 "이 자리에 담을 타입을 나중에 정한다"는 자리표시예요(제네릭). 문서의 E는 Element(요소), K/V는 Key/Value를 뜻하는 관례예요.
예: boolean add(E e)는, 실제로 List<String>을 만들면 E가 String이 되어 add(String e)처럼 읽혀요. 즉 E 자리에 내 타입을 대입해서 읽으면 됩니다.
parseInt(String s)에서 s라는 이름 자체는 중요하지 않아요. "String 타입 값 하나가 필요하다"는 정보가 핵심이에요. 상세 설명의 Parameters: 항목에 각 파라미터가 무슨 의미인지 한 줄로 적혀 있으니 같이 읽으세요.문서는 처음부터 끝까지 읽는 게 아니라 필요한 것만 찾아 읽는 거예요. "문자열을 전부 대문자로 바꾸고 싶다"를 예로, 실전 흐름을 따라가 볼게요.
String을 치거나, 웹 검색으로 "java String uppercase"처럼 찾아 공식 문서(docs.oracle.com) 결과로 들어가요.toUpperCase()가 눈에 띄죠. 이름을 클릭하면 상세로 점프해요.// 문서에서 String.toUpperCase() 를 찾아 확인한 뒤:
String name = "java";
String up = name.toUpperCase(); // "JAVA" ← 반환값을 변수에 받아야 함!
System.out.println(up); // JAVA
System.out.println(name); // java ← 원본 String은 그대로 (불변)String의 메서드들은 원본을 바꾸지 않고 새 값을 "반환"해요. 문서의 Returns 줄을 안 읽고 name.toUpperCase();만 쓰면(반환값을 안 받으면) 아무 일도 안 일어난 것처럼 보여요. 문서를 읽는 습관이 이런 실수를 막아줘요.@since는 "이 메서드가 어느 버전부터 생겼나"(예: @since 9), @deprecated는 "이제 쓰지 말고 대체를 쓰라"는 경고예요. See Also(관련 항목)엔 함께 보면 좋은 메서드·클래스 링크가 걸려 있어, 더 알맞은 메서드를 발견하게 해줘요.문서는 브라우저에서만 보는 게 아니에요. IDE(개발도구) 안에서 코드를 쓰다가 바로 띄울 수 있어, 흐름을 끊지 않고 확인할 수 있어요.
| 활용 | 방법 | 왜 좋나 |
|---|---|---|
| IDE에서 바로 보기 | 메서드에 마우스 호버, 또는 Quick Documentation 단축키(IntelliJ F1·Ctrl+Q, Eclipse F2/Shift+F2) | 브라우저 안 열고 코드 옆에서 즉시 확인 |
| 자동완성 설명 | 메서드 목록이 뜰 때 옆에 나오는 문서 미리보기 | 이름을 다 치기 전에 후보를 비교 |
| 버전 확인 | @since 값을 보고 내 JDK 버전에서 되는지 확인 | "이 메서드는 Java 11부터"라 옛 버전에선 안 됨을 미리 알기 |
| Deprecated 대체 찾기 | 취소선/경고가 보이면 상세의 대체 안내를 따라감 | 곧 사라질 API 대신 권장 API로 갈아타기 |
| 표준부터 습관 들이기 | String·List·Map·Math 등 자주 쓰는 것부터 문서로 확인 | 검색·해석 근육이 붙어 낯선 라이브러리도 쉽게 읽힘 |
자바 API 문서는 오라클 공식 사이트(docs.oracle.com)에서 제공해요. 아래는 2026년 7월 기준으로 유효한 공식 링크예요. 문서 페이지 안에는 대개 버전 셀렉터가 있어, 다른 JDK 버전 문서로 전환할 수 있어요.
@since로 헷갈릴 일이 줄어요. 예를 들어 Java 21로 개발 중이라면 21 문서를 기준으로 보는 게 정확해요.<E>엔 내 타입을 대입해 읽기./** ... */)을 달아두면, javadoc이라는 도구가 그 주석을 읽어 HTML 문서로 자동 생성해요.
| 태그 | 뜻 |
|---|---|
@param | 파라미터(매개변수) 설명 |
@return | 반환값 설명 |
@throws / @exception | 어떤 예외가 언제 발생하는지 |
@since | 이 요소가 도입된 버전 |
@deprecated | 폐기 예정 + 대체 안내 |
@see | See Also(관련 항목) 링크 |
/**
* 문자열을 정수로 바꿔 반환한다.
*
* @param s 숫자로 이루어진 문자열 (예: "123")
* @return 변환된 정수 값
* @throws NumberFormatException 숫자가 아닌 문자열일 때
* @since 1.0
*/
public static int parseInt(String s) throws NumberFormatException {
// ...
}/** */로 문서 주석을 남기면 내 코드의 Javadoc도 자동으로 만들어져요.