Javadoc 1.2 의 신기능 - xrath.com 에서 번역됨

# Javadoc 1.2 의 신기능

Javadoc 에 베풀어진 기능 강화

이 문서에서는, 버젼 1.1 에서 1.2 에의 업그레이드로 Javadoc 에 대해서 행해진 변경에 대해 설명합니다. 내용은, 사용자의 역할에 응해, (1) 다큐멘테이션 코멘트의 기술자에 대하는 것, (2) 도크 렛을 작성하는 개발자에 대하는 것 ( 「아키텍쳐(architecture)」와「도크 렛 API」), (3) javadoc 생성 HTML 페이지의 독자에 대하는 것 ( 「내용」과「형식」)의 3 종류로 나누어집니다. 상세한 것에 대하여는, 이후에의 「변경의 상세」로 설명합니다.

## 변경의 개요

이 개요에서는, 다큐멘테이션 코멘트의 기술자전용의 변경, Javadoc 툴에 대한 변경 (도크 렛 API), 및 Javadoc 의 HTML 출력의 내용과 형식에 대한 변경 (표준 도크 렛의 구현의 경우)에 대해 설명합니다.

> ## 다큐멘테이션 코멘트의 기술

> > ### 다큐멘테이션 코멘트의 기술에 관한 변경

> > 다른 항목으로 다루어지고 있는 기능 중(안)에서, 다큐멘테이션 코멘트의 기술 방법으로 영향을 주는 변경점을 다음에 정리합니다.
> > - 각 클래스의 해설의 최초의 문장은, 요약문이 아니면 안됩니다.
> > - 패키지 레벨의 코멘트를 사용할 수 있게 되었습니다.
> > - 각 패키지의 해설의 최초의 문장은, 요약문이 아니면 안됩니다.
> > - 시스템 전체에 대한 (개요) 코멘트를 사용할 수 있게 되었습니다.
> > - Javadoc 의 새로운 태그를 다큐멘테이션 코멘트로 사용할 수 있게 되었습니다.
> > - 이미지와 샘플을 보관 유지하기 위한 새로운 디렉토리 doc-files 가 카피됩니다.
> > - 계층 구조의 파일이 생성됩니다.
> > - 1.1 으로 1.2 의 다큐멘테이션 코멘트동안에 호환성이 없는 경우가 있습니다.

> ## 아키텍쳐(architecture)

> > ### 도크 렛 API

> > - Javadoc 에, 도크 렛을 기술할 수 있는 도크 렛 API 가 추가되었습니다.

> ## 내용

> > ### 새로운 태그

> > - @throws 태그는 @exception 태그와 동의입니다.
> > - @see 는, 패키지, HTML 의 엥커, 및 인용부호로 둘러싸인 캐릭터 라인을 받아들이게 되었습니다. 또, 라벨도 지정할 수 있습니다.
> > - {@link apiname label} 는, 텍스트 중(안)에서 인 라인 링크를 지정하기 위한 새로운 태그입니다.

> > ### 제공하는 API 정보와 링크의 확충

> > - 패키지 레벨 및 문서 레벨의 정보에 대한 기구가 짜넣어졌습니다.
> > - 멤버의 경우와 같게, 클래스와 패키지에 대해서도 1 행의 요약문이 짜넣어집니다.
> > - 클래스 및 인터페이스의 페이지에, 상속된 API 의 정보가 짜넣어집니다.
> > - 메소드의 개요에는 반환값의 형태가, 필드의 개요에는 필드의 데이터형이, 각각 짜넣어집니다.
> > - 인터페이스를 구현하고 있는 멤버로부터 그 인터페이스에의 링크가 짜넣어집니다.
> > - 각 클래스에는 서브 클래스의 리스트가, 또 각 인터페이스에는 구현하고 있는 클래스가, 각각 짜넣어집니다.
> > - 인터페이스로부터 구현하고 있는 클래스에, 멤버의 기술이 카피됩니다.
> > - 각 패키지에 클래스의 계층 (트리) 표시가 짜넣어집니다.
> > - Javadoc 로 생성된 외부의 문서에 링크하기 위한 -link 옵션이 도입되었습니다.
> > - 추천 되지 않는 API 의 리스트가 짜넣어집니다.
> > - native 및 synchronization 키워드가 제외되게 되었습니다 (Java 의 스펙외).
> > - 이미지와 샘플을 보관 유지하기 위한 새로운 디렉토리 doc-files 가 카피됩니다.

> > ### 커스터마이즈 가능한 타이틀, 헤더, 풋터

> > - 독자적인 타이틀, 헤더, 풋터, 및 보텀 노트를 추가하기 위한 옵션이 도입되었습니다. 보텀 노트란, 저작권 표기나 메일 송신지 링크등의 정보입니다.

> ## 형식

> > ### 이미지 파일

> > - 표제와 조목별로 나누어 쓴 글의 환인에 이미지를 사용하지 않게 되었습니다. 대신에, 겉(표)의 셀과 횡괘선을 사용해 표제와 API 를 구별합니다.

> > ### 스타일 시트

> > - 색, 폰트, 및 배치를 제어하기 위한 HTML 스타일 시트가 추가되었습니다.

> > ### 네비게이션 기능의 향상

> > - 패키지와 클래스의 리스트를 표시하는 HTML 프레임이, 옵션으로서 추가되었습니다. 이 프레임의 표시와 비표시는, 싱글 클릭으로 바꿀 수가 있습니다.
> > - 네비게이션 바가 모든 화면에서 통일되었습니다.
> > - 「API 사용자즈 가이드」가 「헬프」로 변경되었습니다.
> > - 멤버의 개요의 클래스 페이지의 표제로, 「인덱스」가 「개요」로 변경되었습니다.
> > - 개요 섹션과 상세 섹션이 구별하기 쉬워졌습니다.

> > ### 인덱스 기능의 향상

> > - 인덱스를, 최대로 선두 문자 마다 1 파일에까지 분할하는 옵션이 준비되었습니다.
> > - 인덱스가 국제화 되어, Unicode 문자를 처리할 수 있게 되었습니다.
> > - 인덱스에 클래스와 인터페이스가 포함되게 되었습니다.

> > ### 생성처 파일의 계층 구조

> > - 문서 생성처의 디렉토리가, 평탄한 구조로부터 계층 구조로 변경되었습니다. (Beta4 에서의 신기능)

> ## 전반

> > ### 비호환성

> > - Javadoc 1.1 용의 코멘트에 대해서 Javadoc 1.2 를 실행했을 경우에 발생할 가능성이 있는 비호환성에 대해 설명합니다.

> > ### 그 외의 도크 렛

> > - Javadoc 1.1 의 HTML 출력을 생성하는 기능이 계속해 지원됩니다.
> > - ［향후］ FrameMaker 에의 임포트용으로, MIF 출력을 생성하는 기능이 추가됩니다.

> > ### 1.2 이후의 확장 기능의 예정

> > - 단일의 Javadoc 생성 문서를 작성하기 위한 , 추가 생성을 가능하게 합니다.

## 변경의 상세

여기에서는, Javadoc 1.1 에서 1.2 에의 버전 업으로 행해진 변경에 대해 상세하게 설명합니다. 「대응이 끝난 상태」라고 기재되어 있는 항목은, 버젼 1.2 의 Beta4 로 구현되어 테스트된 것입니다.

### 다큐멘테이션 코멘트의 기술에 관한 변경

Javadoc 1.2 에서는, 다음과 같은 요건과 기능이 새롭게 추가되고 있어 다큐멘테이션 코멘트를 기술할 때에 주의가 필요합니다.

> 각 클래스의 해설의 최초의 문장은, 요약문이 아니면 안됩니다.
> 패키지 레벨의 코멘트를 사용할 수 있게 되었습니다.
> 각 패키지의 해설의 최초의 문장은, 요약문이 아니면 안됩니다.
> 시스템 전체에 대한 코멘트를 사용할 수 있습니다.
> Javadoc 의 새로운 태그를 다큐멘테이션 코멘트로 사용할 수 있게 되었습니다.
> 이미지와 샘플을 보관 유지하기 위한 새로운 디렉토리 doc-files 이 카피됩니다.
> 계층 구조의 파일이 생성됩니다.
> 1.1 으로 1.2 의 다큐멘테이션 코멘트동안에 호환성이 없는 경우가 있습니다.

### 아키텍쳐(architecture) - 도크 렛 API

Javadoc 에, 도크 렛을 기술할 수 있는 도크 렛 API 가 추가되었습니다. 이것은, Javadoc 의 아키텍쳐(architecture)에 대한 큰 변경입니다.

> Javadoc 의 도크 렛을 사용하면(자), Javadoc 의 출력을 커스터마이즈 할 수 있습니다. 도크 렛은, 텍스트 변환을 위한 플러그 인이라고 생각할 수가 있습니다. 도크 렛은, 도크 렛 API 에 대해서 기술해서 , Javadoc 툴에 의해 생성되는 출력의 내용과 형식을 지정합니다. HTML, SGML, XML, RTF, MIF 등, 임의의 종류의 텍스트 파일 출력을 생성하기 위한 도크 렛을 작성할 수 있습니다. HTML 형식의 API 문서를 생성하는 「표준」도크 렛이, Sun 로부터 제공되고 있습니다. 게다가 도크 렛을 사용하면(자), API 문서의 생성과는 관계가 없는 특별한 처리를 실시할 수도 있습니다. 예를 들어, 모든 멤버에게 다큐멘테이션 코멘트가 있는 것을 검사하는 진단용 도크 렛을 작성할 수 있습니다.

> 새로운 아키텍쳐(architecture)이 채용된 이유 - 지금까지의 Javadoc (1.0.x 로 1.1.x)에서는, 입력으로서 Java 의 원시 파일을 사용해, 출력으로서 HTML 를 생성합니다. HTML 출력의 형식은, Java 중(안)에서 고정적으로 코딩 되고 있습니다. 이러한 아키텍쳐(architecture)의 결점은, 소스의 라이센스를 소유하고 있어, 매우 난해한 코드를 수정하는 의욕이 없는 한, 출력을 커스터마이즈 할 수 없다고 하는 것입니다. 즉, 단어의 선두 문자의 대문자화나 색의 변경이나 볼드의 추가등이 작은 수정이든, MIF 나 RTF 등이 새로운 형식에의 변환과 같이 큰 수정이든, 테크니컬 라이터는 필요한 확장을 실시할 수 없습니다.

> Javadoc 의 아키텍쳐(architecture) 변경의 요건은, 다음과 같은 것이었습니다.

> - 입력 소스의 구문 분석과 처리에 사용되는 기구를, 출력 형식의 스펙으로부터 떼어낸다

> - 출력 형식의 스펙을 플러그 인 가능하게 한다

> - 출력 형식의 스펙을, 테크니컬 라이터의 요구로 할 수 있는 한 폭넓게 대응할 수 있도록(듯이) 한다
> 새로운 아키텍쳐(architecture) :javadoc 의 프론트엔드는, 커멘드행의 인수를 처리해, Java 의 구문 분석과 처리를 실시해, 루트 데이터 구조를 구축해, 그것을 Java 의 「도크 렛」에 건네줍니다. 도크 렛은, 패키지, 클래스, 메소드, 필드, 코멘트, 및 이러한 객체의 열거를 나타내는 API 를 개입시켜, 이 데이터에 액세스 합니다. 이 API 에 대해서 새로운 도크 렛을 기술하는 일도, 표준 도크 렛을 서브 클래스화해 작은 변경을 더하는 일도 가능합니다.

### 내용 - 새로운 태그

여기서 설명하는 태그는, 실제로는, 표준 도크 렛은 아니고, Javadoc API 중(안)에서 구현되고 있습니다.

> 새로운 태그 @throws 는, @exception 와 동의의 태그입니다. 「throws」는 Java 언어의 키워드이므로, 알기 쉬워집니다.

> 기존의 태그 @see 가, 패키지, HTML 의 엥커, 및 인용부호로 둘러싸인 캐릭터 라인을 받아들이게 되었습니다. 또, 라벨도 지정할 수 있습니다. @see 태그에서는, 클래스, 메소드, 또는 다른 API 를 참조하는 경우와 같이, 패키지를 참조할 수 있습니다. HTML 의 엥커는 「`<a href="xxx">XXX</a>`」의 형식에서 지정해, 인용부호로 둘러싸인 캐릭터 라인은 「"xxx"」의 형식에서 지정합니다. 예로서Javadoc 의 레퍼런스 페이지를 참조해 주세요. 라벨은 필요에 따라서 지정할 수 있어 형식은 「@see 이름 라벨」입니다. 라벨을 지정했을 경우는, 이름 대신에 라벨이 표시됩니다.

> 새로운 태그 {@link apiname label} 는, 텍스트 중(안)에서의 인 라인 링크의 지정에 사용합니다. 구버젼의 Javadoc 의 경우, API 에 링크를 포함하려면 , @see 태그를 사용하는지, HTML 를 하드 코드 할 수 밖에 방법이 없었습니다. 이 새로운 인 라인 태그에서는, @see 로 HTML 링크를 생성하기 위해서 사용되고 있는 것과 같은 알고리즘이 사용됩니다. 양자의 차이는,[관련 항목] 표제아래는 아니고, 인 라인에 링크가 놓여지는 점입니다.

### 내용 - 제공하는 API 정보와 링크의 확충

> 패키지 마다, 다큐멘테이션 코멘트 전용의 파일 (이름은 「package.html」)이 1 개, 소스 트리에 추가되게 되었습니다. 각 패키지의 해설의 최초의 문장은, 요약문입니다. Javadoc 는, <body> 와 </body> 의 사이에 있는 모든 것을 꺼내, 패키지의 개요 페이지 package-summary.html 에 추가합니다. 이 페이지에는, 클래스와 인터페이스의 일람표도 포함되어 있습니다. Javadoc 는, 이 최초의 문장을, 개요 페이지인 overview.html 에 카피합니다. 따라서, <body> 와 최초의 문장의 사이에, 타이틀이나 다른 텍스트를 삽입할 수 없습니다.

> 패키지 레벨의 코멘트의 개략은 다음과 같습니다.

> - 처음에
> - 패키지의 스펙
> - 관련 문서

> 상세한 것에 대하여는,「Package-Level Doc Comments」를 참조해 주세요.

>   구스펙:Javadoc 1.1 의 경우, 특정의 패키지에 고유의 코멘트를 기술할 수 없습니다.

>   > 주 - 상기의 기능을 사용하는 경우는, 새로운 Javadoc 의 규칙에 따라 다큐멘테이션 코멘트를 기술할 필요가 있습니다. 각 패키지의 해설의 최초의 문장은, 요약문이 아니면 안됩니다.

> 일식의 패키지에 대해서, 시스템 전체를 대상으로 하는 1 개의 문서 overview.html 가 추가되게 되었습니다. 이 파일에는, 문서화 떠날 수 있어 모든 패키지에 들어맞는 코멘트가 들어갑니다. 예를 들어, 이 페이지에서는, 「특히 기재가 없는 한, null 가 건네받으면(자) 항상 NullPointerException 가 throw 된다」등이 같은 전제 사항을 문서화할 수 있습니다.

> 이 파일은 소스 트리에 속해, 임의의 파일명을 지정할 수 있습니다. 일반적으로, overview.html 라는 이름을 사용합니다. Javadoc 를 실행할 경우에, 커멘드행으로 -overview 옵션에 이 파일명을 지정하면(자), 그 파일의 내용 (<body> 태그와 </body> 태그의 사이)이, 우측의 프레임에 표시되는 overview-summary.html 이라는 이름의 초기 페이지 (Beta3 이전의 버젼에서는 packages.html 라는 이름)에 삽입됩니다.

>   구스펙:Javadoc 1.1 의 경우, 모든 패키지에 들어맞는 코멘트를 기술할 수 없습니다.

> 각 패키지를 1 행으로 요약한 최초의 문장이 package.html 로부터 꺼내져, packages.html 에 포함되게 되었습니다. 이것에 의해, 전패키지의 리스트에, 각 패키지의 개요가 표시됩니다.
>   구스펙:Javadoc 1.1 의 경우, 이러한 개요 리스트의 기능은 없습니다.

> 각 클래스의 해설의 최초의 문장이 꺼내져 package-<class>.html 의 클래스 개요에 포함됩니다. 이것에 의해, 특정의 패키지에 대해 모든 클래스의 개요가 제공됩니다.
>   구스펙:Javadoc 1.1 의 경우, 이러한 개요 리스트의 기능은 없습니다.

>   > 주 - 상기의 기능을 사용하는 경우는, 새로운 Javadoc 의 규칙에 따라 다큐멘테이션 코멘트를 기술할 필요가 있습니다. 각 클래스의 해설의 최초의 문장은, 요약문이 아니면 안됩니다.

> 클래스 및 인터페이스의 페이지의 메소드 개요와 필드 개요에, 상속된 API 가 추가되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 특정의 클래스에 도착해 상속된 멤버는 그 클래스의 페이지에는 표시되지 않고, 링크를 더듬어 조사할 필요가 있습니다.

> 메소드 개요의 시그니챠에, 반환값의 형태와 키워드 static, protected, 및 abstract 가 짜넣어지게 되었습니다. 이러한 정보는, 메소드를 호출할 때에 필요하기 때문에입니다. 다만, public, transient, volatile, 또는 final 는 짜넣어지지 않습니다. 이것들은, 페이지의 한층 더 아래의 상세 섹션에 표시됩니다. 필드의 데이터형은 짜넣어집니다.
>   구스펙:Javadoc 1.1 의 경우, 메소드의 개요에 반환값의 형태는 표시되지 않습니다. 또, 필드의 개요에 필드의 데이터형은 표시되지 않습니다.

> 인터페이스를 구현하는 멤버에게 「정의」가 추가되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 인터페이스를 구현하는 클래스의 멤버에게 이러한 항목은 표시되지 않습니다.

> 클래스 페이지의 선두에 서브 클래스의 리스트가 추가되었습니다. 또, 인터페이스 페이지의 선두에, 서브 인터페이스 및 구현하는 클래스가 추가되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 클래스 페이지에 서브 클래스의 리스트는 표시되지 않습니다.

> 구현하는 메소드에 텍스트가 포함되지 않은 경우에 한정해, 인터페이스의 메소드로부터 그 구현하는 서브 클래스에, 자동적으로 해설이 카피되게 되었습니다. 이 때, 그 텍스트가 인터페이스로부터 카피된 것을 나타내는 같은 내용의 문장이 짜넣어집니다. 이러한 처리를 실시하는 이유는, 인터페이스를 구현하는 경우, 인터페이스와 클래스의 양쪽 모두로 메소드의 해설이 완전히 같다라고 하는 것이 많기 때문입니다. 수작업으로 기술을 카피하는 것은, 유지 관리가 귀찮아, 쓸데없는 작업입니다.
>   구스펙:Javadoc 1.1 의 경우, 메소드의 해설은 인터페이스로부터 카피되지 않습니다.

> 패키지마다의 트리 표시가 추가되었습니다. 패키지 또는 클래스를 표시했을 때의 트리 표시는, 이 트리 표시에 링크하고 있어, 거기로부터 한층 더 전패키지의 트리에 링크하고 있습니다.
>   구스펙:Javadoc 1.1 의 경우, 단일의 패키지에 대한 트리 표시 (클래스 계층)는 없습니다. 유일한 트리 표시는 전패키지에 대한 것으로, JDK 의 경우, 이것은 거대한 트리가 됩니다.

> 외부의 Javadoc 생성 문서에 링크하기 위한 -link 옵션이 도입되었습니다. 디폴트에서는, 외부 문서에는 링크되지 않습니다. 문서를 생성할 때에, -link 옵션을 지정하면(자), 문서화하고 있는 API 로부터 참조하고 있는 API 의 문서에의 링크가 생성됩니다. 링크는, 로컬 또는 원격 (인터넷상)의 어느쪽이나 가능합니다.
>   구스펙:Javadoc 1.1 의 경우, 생성하고 있는 문서로부터 외부에의 링크는 작성되지 않습니다.

> Javadoc 로 문서화해야 하는 것이 아닌 디폴트의 생성자 에 대해, 버그를 제출했습니다. 디폴트의 생성자 은, 추천 되지 않는 것으로서 기재하는지, 버그라고 봐, 문서로부터 제외할 필요가 있습니다.
> (Javadoc 에는 영향 없음)
>   구스펙:Javadoc 1.1 의 경우, 어플리케이션 개발자가 그것을 호출할지 어떨지에 관계없이, 디폴트의 생성자 이 모두 짜넣어지게 되어 있습니다. 디폴트 생성자 을 문서화할 때, 해설은 공백이 됩니다.

> 추천 되지 않는 API 를 모두 일람표시 하는 개요 페이지가 추가되었습니다. 최종적으로는, 옮겨놓을 수 있었던 API 에의 링크가 추가될 예정입니다.
>   구스펙:Javadoc 1.1 의 경우, 추천 되지 않는 API 의 리스트는 생성되지 않습니다.

> 추천 되지 않는 클래스에 표를 붙일 수 있게 되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 특정의 패키지의 클래스 리스트로, 추천 되지 않는 클래스에 그것을 나타내는 표는 붙지 않습니다.

> 시그니챠로부터 synchronized 와 native 가 삭제되었습니다. Javadoc 는 API 의 스펙을 생성합니다. 이것들 2 개의 키워드는, 구현에 고유의 것이므로, 스펙의 시그니챠에는 포함되지 않습니다. 키워드 native 는, 문서화할 필요가 없습니다. 키워드 synchronized 는, thread에 대해서 안전한 동작을 나타내고 있어 오히려 메소드의 해설에 기술해야 할 것입니다. thread에 대해서 안전한 메소드 자체가 synchronized 키워드를 사용하지 않는 경우에서도, 그러한 private 메소드를 호출하는 경우가 있습니다.
>   구스펙:Javadoc 1.1 의 경우, 키워드 synchronized 와 native 가 짜넣어집니다.

> 이미지와 샘플을 보관 유지하기 위한 doc-files 디렉토리가, 각 패키지에 1 개씩 카피되게 되었습니다. Javadoc 는, 소스 트리의 각 패키지의 디렉토리에서 doc-files 라는 이름의 디렉토리를 찾아, 이 이름의 디렉토리와 그 내용을 문서의 생성 먼저 카피합니다. doc-files 디렉토리내의 파일은, 단지 생성 먼저 카피되는 것만으로, 처리는 베풀어지지 않습니다. 즉, 이러한 파일에 표준의 네비게이션 바, 헤더, 또는 풋터를 더할 수 없습니다. 또 인덱스나 트리에 이러한 파일을 더할 수도 있습니다. 이 디렉토리에는, 다큐멘테이션 코멘트로부터 참조하는 임의의 파일을 둘 수가 있습니다. 예:이미지, HTML 파일, 텍스트 파일, 샘플 원시 코드, 복수의 클래스에서 공유되는 HTML 테이블등을 포함할 수 있습니다.

> 예:java.awt.Button 클래스의 해설안에 이미지 파일 Button-1.gif 에의 참조를 짜넣으려면 , 다음과 같이 합니다.

> - 소스 트리로, java/awt/ 디렉토리아래에 doc-files 라는 이름의 디렉토리를 만듭니다.
> - doc-files 디렉토리에 Button-1.gif 파일을 둡니다.
> - Button 클래스의 다큐멘테이션 코멘트에 <img> 태그를 추가합니다.

>          /**
>           * <img src="doc-files/Button-1.gif">
>           */

> Java Software 에서는, 「-1」으로 시작되어, 그 이후의 이미지에 대해서는 숫자를 1 두개 늘려 가는 명명 규칙을 채용하고 있습니다. 상세한 것에 대하여는,「Including Images」를 참조해 주세요.
>   구스펙:Javadoc 1.1 의 경우, Javadoc 를 실행해도 이미지가 생성 먼저 카피되지 않기 때문에, 링크가 망가진 파일이 생성됩니다. JDK 의 현상을 보면(자), 이러한 이미지의 대부분은, AWT 및 Swing 컴퍼넌트의 screen shot입니다.

### 내용 - 커스터마이즈 가능한 타이틀, 헤더, 풋터

> 선두 페이지 packages.html 에 타이틀을 집어 넣기 위한 -title 옵션이 추가되었습니다. 타이틀의 예:Java Platform 1.2 Core API
>   구스펙:Javadoc 1.1 의 경우, 생성 문서에 타이틀을 추가하는 정규의 방법은 없습니다.

> 각 페이지에 헤더, 풋터, 및 보텀 노트를 더하기 위한 -header, -footer, -bottom 의 각 옵션이 추가되었습니다. 이 기능을 사용하면(자), API 의 버젼 번호 (Java 1.2 Beta4 등)를 각 페이지에 출력해, 페이지를 인쇄했을 때에, 생성원의 API 의 버젼을 기록할 수 있습니다. 「보텀 노트」기능을 사용하면(자), 각 페이지의 하단에, 저작권 표기나 피드백용의 전자 메일 링크를 추가할 수 있습니다.
>   구스펙:Javadoc 1.1 의 경우, 디폴트로 각 페이지에 버젼 번호를 표시할 수 없습니다.

### 내용 - 원시 파일에의 링크를 더하지 않는다

> 내부에서 행해지는 개발의 경우, Javadoc 로 생성되는 클래스 페이지로부터 원시 코드에 직접 링크되고 있으면(자) 편리합니다. 그러나, API 문서를 생성해 공개할 때, Java API 의 문서에 Java 원시 코드에의 링크를 짜넣지 않는 것이 정해졌습니다. 따라서, 표준 도크 렛에 대한 이 기능의 추가도, 우선도가 낮아졌습니다. 다만, 이것과는 별도로,원시 코드에의 링크를 생성하는 도크 렛을 이용할 수 있습니다.

### 형식 - 이미지 파일

> 필수의 GIF 이미지가 없어졌습니다. GIF 이미지의 환인은, 횡괘선으로 옮겨집니다. 또, 그래픽 이미지의 표제 ( 「메소드」, 「필드」등) 대신에, 겉(표)의 색첨부의 셀에 표제의 텍스트가 배치됩니다.
>   구스펙:Javadoc 1.1 의 경우, 환인과 표제에 GIF 이미지가 사용되고 있습니다. 이러한 GIF 이미지는 필요 없습니다. GIF 이미지를 사용하면(자), 표시가 늦어져, 문서의 생성 먼저 이미지를 수작업으로 카피할 필요가 있습니다.

### 형식 - 스타일 시트

> 색, 폰트, 및 배치를 제어하기 위한 HTML 스타일 시트가 추가되었습니다. 스타일 시트는, Web 페이지의 텍스트의 색, 폰트, 및 배치를 실행시로 설정하는 표준화 된 방법입니다. 겉(표)의 셀의 색이나 좌측의 프레임에 표시되는 폰트의 사이즈를 변경하려면 , javadoc 가 생성하는 파일 `stylesheet.css` 를 수정합니다. 또, -stylesheetfile 옵션을 사용하면(자), javadoc 를 실행할 경우에 독자적인 스타일 시트를 지정할 수 있습니다.

> 예를 들어, 표제의 셀의 배경색을 진한 파랑으로부터 흰색으로 변경하려면 ,`stylesheet.css` 파일을 다음과 같이 편집합니다.

> 편집전:

>        #TableHeadingColor     { background: #CCCCFF } /* Dark mauve */

> 편집 후:

>        #TableHeadingColor     { background: #FFFFFF } /* Dark mauve */

> 공식의 해설에 대해서는, W3C 의 Web 페이지「Cascading Style Sheets」를 참조해 주세요. 사용 방법에 대한 상세한 설명은, CNET 의 Web 페이지「CSS Reference Table」를 참조해 주세요. 개요 설명을 보는 경우는, 「CSS Reference Table」의 페이지로 [back to intro] 를 클릭해 주세요.

### 형식 - 네비게이션 기능의 향상

> 패키지, 클래스, 및 멤버를 위한 프레임이 추가되었습니다. 프레임 없음의 경우는, package-summary.html 로부터 시작됩니다. 프레임 있는 경우는, overview-summary.html 로부터 시작됩니다.
>   구스펙:Javadoc 1.1 의 경우, 임의의 패키지, 클래스, 또는 멤버에게 액세스 하는 간단한 방법은 없습니다. 거슬러 올라가 스스로 찾을 필요가 있습니다.

> 패키지 리스트의 상단 (좌상의 프레임)에 [모든 클래스] 링크가 추가되었습니다. 이 링크를 클릭하면(자), 알파벳순서에 줄선 모든 클래스의 리스트가 좌하의 프레임에 표시됩니다.
>   구스펙:Javadoc 1.1 의 경우, 패키지안에 있을지 어떨지에 관계없이, 임의의 클래스에 액세스 하는 간단한 방법은 없습니다. 「클래스 계층」을 표시할 필요가 있습니다. 클래스와 인터페이스만의 리스트가 있으면(자) 편리합니다.

> 모든 화면에서 사용할 수 있는 단일의 네비게이션 바가 준비되었습니다. 사용할 수 없는 항목은 엷은 색 표시됩니다.
>   구스펙:Javadoc 1.1 의 경우, 화면의 상단에 표시되는 표준의 네비게이션 바는, 페이지에 의해 크게 다릅니다. 전패키지용 (2 항목), 단독의 패키지용 (3 항목), 클래스용 (6 항목)이라고 하는 3 종류의 네비게이션 바가 있습니다.

> 각 서브 섹션에 이동하기 위한 , 다른 네비게이션 바가 추가되었습니다.
> 개요:내부 클래스 | 필드 | 생성자 | 메소드 상세:필드 | 생성자 | 메소드
>   구스펙:Javadoc 1.1 의 경우, 멤버의 개요와 상세를 표시하려면 , 클래스의 해설을 스크롤 해 먼저 진행되지 않으면 안됩니다.

> [API 사용자즈 가이드] 링크는 [헬프] 로 이름이 변경되었습니다. 디폴트의 헬프 파일을 생성하도록(듯이), Javadoc 가 변경되었습니다. 필요에 따라서 [헬프] 링크를 네비게이션 바로부터 삭제할 수 있도록(듯이), -nohelp 옵션이 추가되고 있습니다. 또, 파일의 작성을 지정한다 -helpfile 옵션이 추가되고 있습니다.
>   구스펙:Javadoc 1.1 의 경우는,[API 사용자즈 가이드] 라고 하는 링크가 packages.html 에 작성됩니다. 이 링크가 가리키고 있는 파일은, 문서 생성처의 디렉토리에 자동적으로는 카피되지 않습니다.

> Javadoc 1.2 에서의 멤버용의 HTML 프레임. 표준 도크 렛에 이 기능을 추가할지 어떨지 검토되었습니다만, 추가하지 않게 되었습니다. 서드 파티의 개발자가 별개의 도크 렛으로 이 기능을 릴리스 하면(자), 공표할 예정입니다.

### 형식 - Web 페이지

> 개요의 표시가, 테두리와 배경색이 있는 셀로 구성되는 겉(표)로 바뀌었습니다. 이 표시 방법 쪽이, 클래스 파일의 개요 부분과 상세 부분을 간단하게 구별할 수 있습니다.
>   구스펙:Javadoc 1.1 의 경우, 개요 부분과 상세 부분의 표시가 자주(잘) 비슷하기 (위해)때문에, 스크롤 다운했을 때에 어느 쪽의 부분이 표시되고 있을까 확실하지 않습니다.

> 「인덱스」라고 하는 이름은, 문서의 마지막에 있는 알파벳순서의 API 리스트를 가리킵니다. 패키지마다의 페이지의 선두 부분의 이름이, 「패키지의 인덱스」로부터 「패키지의 개요」로 변경되었습니다. 같이 클래스마다의 페이지의 선두에 있는 부분의 이름이, 「메소드의 인덱스」는 「메소드의 개요」에, 「생성자 의 인덱스」는 「생성자 의 개요」에, 「필드의 인덱스」는 「필드의 개요」에, 각각 변경되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 「인덱스」라고 하는 말이, 클래스의 페이지의 선두에 있는 개요와 전 API 의 알파벳순서의 리스트의 양쪽 모두에 대해 사용되고 있습니다. 이것은, 불필요한 혼란을 부릅니다.

### 형식 - 인덱스 기능의 향상

> 인덱스를 알파벳 마다 다른 파일에 분할한다 -breakindex 옵션이 추가되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 인덱스의 파일은 JDK 로 1.4M 바이트라고 하는 거대한 것이 되어, 인터넷 경유로 로드하는데 시간이 너무 걸립니다.

> 인덱스에 클래스와 인터페이스가 추가되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 인덱스에는 생성자 과 멤버만이 표시되어 클래스와 인터페이스는 포함되지 않습니다.

> 인덱스가 국제화 되어 Unicode 문자를 이용할 수 있게 되었습니다.
>   구스펙:Javadoc 1.1 의 경우, 인덱스로 처리할 수 있는 문자는 알파벳의 A ? Z 뿐입니다 (실제는 A ? Y 만).

### 형식 - 생성처 파일의 계층 구조

> 문서 생성처의 디렉토리에 계층 구조가 추가되었습니다. 원시 코드의 트리를 반영하도록(듯이), 서브 패키지 마다 1 개의 디렉토리가 작성됩니다. 평탄한 디렉토리 구조는 지원되지 않게 되었습니다. 패키지 단위로 파일이 분산되므로, 각 디렉토리내의 파일수가 적게 된다고 하는 효과가 있습니다. 또, 패키지명이 파일명의 일부에서는 없고 디렉토리명으로 표현되기 (위해)때문에, 파일명이 짧아진다고 하는 부차 효과도 있습니다. 이것에 의해, 서드 파티는, 의미가 있는 짧은 이름 (Macintosh 용의 31 문자의 이름등)을 간단하게 생성할 수 있게 됩니다.

> 예를 들어,`java.awt.Button.html` 는 `\java\awt\Button.html` 가 됩니다. 1.2 에서의 변경을 모두 적용하면(자), java.applet 패키지에 대해서 Javadoc 를 실행했을 경우, 문서 생성처 파일의 구조는,「생성되는 파일 구조」로 설명되고 있는 대로 됩니다.

>   구스펙:Javadoc 1.1 에서는 평탄한 구조가 사용되고 있어 HTML 파일은 모두 1 개의 디렉토리에 배치됩니다.

### 비호환성

> 1.1 으로 1.2 의 사이로, 다큐멘테이션 코멘트에 호환성이 없는 경우가 있습니다. Javadoc 1.2 는, Javadoc 의 구버젼용으로 쓰여진 다큐멘테이션 코멘트와의 호환성을 고려해 작성되었습니다. 그렇다고는 해도, 낡은 다큐멘테이션 코멘트를 Javadoc 1.2 로 컴파일 하면(자), 그것까지와는 다른 「동작」을 하는 경우가 있습니다.

> - 많은 파일명이 변경되었습니다. 무엇보다 중요한 변경은, 생성 문서의 초기 페이지가, packages.html 는 아니고, index.html (HTML 프레임을 설정하는 파일)가 된 것입니다. 프레임을 표시하지 않는 경우는, overview-summary.html 를 초기 페이지로서 로드합니다 (이 페이지는, 1.1 에서의 packages.html 에 해당된다).

> - 코멘트의 기술자가, 코멘트의 텍스트안에, API 명에의 인 라인 링크를 고정적으로 기술하고 있었을 경우가 있습니다. javadoc 가 계층 구조의 디렉토리를 생성하게 되었기 때문에, 이러한 링크는 올바르게 기능하지 않습니다. 새로운 `{@link}` 태그를 사용하면, 인 라인 링크를 올바르게 기술할 수 있습니다.

### 그 외의 도크 렛

> Javadoc 1.1 의 문서 형식은, 독자적인 도크 렛으로서 남아 있습니다. 이 도크 렛에서는, 낡은 표시 형식과 평탄한 디렉토리 구조가 사용됩니다만, 버그의 일부가 새롭게 수정되고 있습니다. Javadoc 1.1 형식을 이용하려면 , javadoc 의 「-1. 1」옵션을 사용합니다.
>   구스펙:Javadoc 1.1 형식은, 그 형식의 HTML 출력을 처리하는, 그 형식에 의존한 퍼서를 개발한 사용자에게 있어 중요합니다.

> [향후] MIF 의 도크 렛을 구현합니다. 이것에 의해, MIF 형식의 출력을 생성하는 기능이 추가되어, FrameMaker 에 임포트 할 수 있게 됩니다.
> (1.2 이후에 실시 및 릴리스 될 예정)
>   구스펙:Javadoc 1.1 에는 MIF 의 출력 기능은 없습니다. 다만, Javadoc 1.0. 2 에는 있습니다.

### 장래의 확장 기능 - 1.2 이후의 릴리스

> 단일의 Javadoc 생성 문서를 작성하기 위한 , 추가 생성을 가능하게 합니다. Javadoc 를 실행할 때마다 중간 형식을 보존해, 이 중간 형식을 머지 해, 정확한 인덱스, 트리, 클래스 계층, 서브 클래스 리스트등을 갖춘 완전한 문서를 생성할 수 있도록(듯이) 합니다.
> (미대응 - 1.2 보다 나머지의 릴리스로 대응의 예정)
>   구스펙:Javadoc 1.1 의 경우, 문서의 추가 생성은 할 수 없습니다.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. | Java Software