「태그 렛의 개요」 - xrath.com 에서 번역됨

# 「태그 렛의 개요」

## 목차

- 태그 렛 API
- 태그 렛의 기술
- 예 - 블록 태그 렛
- 예 - 인 라인 태그 렛
- 에러 및 경고의 처리

## 태그 렛 API

태그 렛은, JavaTM 프로그램 언어로 기술한 프로그램이며, 태그 렛 API 를 구현하고 있습니다. 태그 렛은, 블록 태그 (예를 들어 `@todo`) 또는 인 라인 태그 (예를 들어 `{@underline}`)의 어느쪽이든으로서 기술할 수 있습니다. 현재로서는, 블록 태그 렛은, 그 텍스트내에서 인 라인 태그를 지원하고 있습니다. (「블록 태그와 인 라인 태그」를 참조해 주세요. ) 태그 렛 API 는, 다음의 1 개의 인터페이스로 구성되어 있습니다.

- Taglet 인터페이스

태그 렛을 사용하면(자), 커스텀 태그의 텍스트 인수의 수정이나 서식 지정이 가능하게 되는 것 외에 텍스트를 파일이나 그 외의 스트림에 리다이렉트(redirect) 하는 등, 다양한 처리를 실행할 수 있습니다. 태그 렛에 의해 표준 태그를 오버라이드(override) 할 수도 있습니다.

태그 렛은,`-tag` 옵션의 기반이 되는 기능입니다. `-tag` 옵션을 사용하면(자), 편입 태그 렛이 사용되어,`@return` 에 대해서 생성되는 것 과 유사한 디폴트 HTML 형식이 생성됩니다.

## 태그 렛의 기술

태그 렛은, 다음의 기본 순서에 따라 작성해, 사용합니다.

1. 태그 렛이 되는 Java 프로그램을 기술합니다. 프로그램은 다음의 것을 임포트 할 필요가 있습니다.

          import com.sun.tools.doclets.Taglet;    // Taglet API
          import com.sun.javadoc. *;               // Doclet API
          import java.util.Map;                   // Used in register(Map)

   `com.sun.javadoc` 의 클래스는,`toString(Tag)` 로 사용하는 `Tag` 인터페이스를 위해서(때문에) 임포트 할 필요가 있습니다.

2. 작성하는 클래스에서는, 그 클래스가 상속하는 인터페이스로 필요한 것을 구현하지 않으면 안됩니다. `toString` 메소드안에, 커스텀 태그에게 건네지는 텍스트 인수의 수정, 서식 지정, 또는 리다이렉트(redirect)를 실행하기 위한 커스텀 처리를 구현합니다.

           public String toString(Tag tag)

3. 구현하고 있는 인터페이스로 필요한 것에 가세해, 다음의 static 메소드를 구현할 필요가 있습니다. 그 후, 실행시에 로드 되도록(듯이) 태그 렛을 유효화합니다. 이후에의예에 있는 원시 코드를 참조해 주세요.

           public static void register(Map tagletMap)

4. 도크 렛을 컴파일 합니다. 거기에는, JDK 에 포함되어 있는 javac 컴파일러의 버젼 1.4. 0 이후를 사용합니다. 필요한 클래스 파일은, JDK 의 `lib\tools.jar` 파일에 포함되어 있습니다. 이후에의 최초의 예에서는, JDK 의 인스톨처를 `C:\Program Files\j2sdk1. 4.1` 으로 상정하고 있습니다.

          javac -classpath "C:\Program Files\j2sdk1. 4.1\lib\tools.jar"  ToDoTaglet.java

5. `-taglet` 옵션 및 `-tagletpath` 옵션을 사용해 javadoc 툴을 실행합니다. 예를 들어, 태그 렛의 클래스 파일을 `com.sun` 패키지내에 들어갈 수 있도록(듯이) 정의되고 있어 `C:\taglets\com\sun\Taglet.class` 에 코드가 포함되고 있는 경우는, tagletpath 에 `C:\taglets` 를 설정합니다. 이 예에서는,`ToDoTaglet` 태그가 짜넣어지고 있는 `com.package1` 패키지를 지정해 `javadoc` 를 호출하고 있습니다.

          javadoc -taglet ToDoTaglet -tagletpath C:\taglets com.package1

이후에의 예에서는, 블록 태그 렛 및 인 라인 태그 렛에 대해 설명합니다.

## 예 - 블록 태그 렛

> `@todo` 를 구현하는 블록 태그 렛의 예의 원시 코드는, 다음의 파일에 포함되어 있습니다.
> - `ToDoTaglet.java`
> 대응하는 클래스 파일인 `ToDoTaglet.class` 는, 벌써 컴파일 되어 이 원시 파일과 같은 디렉토리내에 보존되고 있습니다.

> 이 태그 렛은,`@todo` 태그의 출력 형식을 지정합니다. 다음의 태그를 포함한 다큐멘테이션 코멘트는,

>         /**
>          * @todo Fix this!
>          */

> `ToDo` 태그 렛에 의해, 다음과 같은 HTML 출력에 서식 지정됩니다.

> > To Do:

> >   Fix this!

> ### 구현에 관한 설명

> 원시 코드를 봅시다. 태그에 이름을 붙여 헤더 텍스트를 정의하려면 , 2 개의 private 필드를 정의합니다.

>         private static final String NAME = "todo";
>         private static final String HEADER = "To Do:";

> 인 라인 태그는 아니고 블록 태그로 하기 (위해)때문에,`isInlineTag` 가 false 를 돌려주도록(듯이) 설정합니다.

>         public boolean isInlineTag() {
>             return false;
>         }

> `inField`,`inMethod`,`inType`,`inPackage`,`inOverview` 라고 한 다른 메소드에서도,`true` 또는 `false` 를 지정해, 이 태그를 사용할 수 있는 원시 코드의 다큐멘테이션 코멘트를 나타냅니다.

> `toString(Tag)` 메소드에서는, 1 개의 `{@todo}` 태그에 조우했을 때, 텍스트를 어떻게 출력에 삽입할까를 결정합니다. 이 코드는, 굵은 글씨의 표제의 뒤,`tag.text()` 로 지정된 텍스트를 포함한 황색의 배경의 겉(표)를 작성합니다.

>         public String toString(Tag tag) {`
>             return "<DT><B>" + HEADER + "</B><DD>"
>                    + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
>                    + tag.text()
>                    + "</td></tr></table></DD>\n";
>         }

> 같이`toString(Tag)` 메소드 (태그의 1 배열을 취득한다)에서는, 복수의 `{@todo}` 태그에 조우했을 때, 텍스트를 어떻게 출력에 삽입할까를 결정합니다.

> register 메소드는 다음과 같습니다.

>         /**
>          * Register this Taglet.
>          * @param tagletMap  the map to register this tag to.
>          */
>         public static void register(Map tagletMap) {
>            ToDoTaglet tag = new ToDoTaglet();
>            Taglet t = (Taglet) tagletMap.get(tag.getName());
>            if (t ! = null) {
>                tagletMap.remove(tag.getName());
>            }
>            tagletMap.put(tag.getName(), tag);
>         }

## 예 - 인 라인 태그 렛

> 블록 태그와는 달라, 커스텀인 라인 태그는, 태그 렛을 사용해서만 구현할 수 있습니다. 즉,`-tag` 옵션을 사용해 구현할 수 없습니다. 이것은, 인 라인 태그에는 디폴트의 동작이 없기 때문입니다.

> `{@underline}` 를 구현하는 인 라인 태그 렛의 원시 코드의 예는, 다음안에 포함되어 있습니다.

> - `UnderlineTaglet.java`
> 대응하는 클래스 파일인 `UnderlineTaglet.class` 는, 벌써 컴파일 되어 이 원시 파일과 같은 디렉토리내에 보존되고 있습니다.

> 이 태그 렛은,`{@underline}` 태그의 출력 형식을 지정합니다. 다음의 태그를 포함한 다큐멘테이션 코멘트는,

>         /**
>          * Be sure to insert the value at the {@underline start} of the array.
>          */

> 다음과 같이 HTML 로 출력됩니다.

> > Be sure to insert the value at the start of the array.

> ### 구현에 관한 설명

> 이 원시 코드 (인 라인 태그 렛)와 전출의 예 (스턴트 아론 태그 렛)와의 차이를 봅시다. 물론, 태그명은 달라, 인 라인 태그에는 헤더가 없기 때문에 정의되고 있지 않습니다.

>         private String NAME = "underline";

> 블록 태그는 아니고 인 라인 태그로 하기 (위해)때문에,`isInlineTag` 가 true 를 돌려주도록(듯이) 설정합니다.

>         public boolean isInlineTag() {
>             return true;
>         }

> `inField`,`inMethod`,`inConstructor`,`inType`,`inPackage`, 및 `inOverview` 의 각 메소드는, 블록 태그에게만 적용됩니다. 그 때문에, 인 라인 태그에서는 모두 false 를 돌려주도록(듯이) 설정할 필요가 있습니다.

> `toString(Tag)` 메소드에서는, 1개의 `{@underline}` 태그에 조우했을 때, 텍스트를 어떻게 출력에 삽입할까를 결정합니다. 이 코드는, HTML 밑줄 태그 `<ul>` 및 `</ul>` 로 텍스트를 둘러쌉니다.

>         public String toString(Tag tag) {
>             return "<u>" + tag.text() + "</u>";
>         }

> 블록 태그의 경우와는 달라, 인타인타그의 배열을 처리할 수 없습니다. 그 때문에, 인 라인 태그에서는,`toString(Tag[])` 메소드 (태그의 1 배열을 취득한다)는 무시됩니다.

## 에러 및 경고의 처리

> 에러 - 태그 렛은, 에러 메세지를 표시해,`System.exit()` 를 호출하는 것만으로, 에러를 보고해, Javadoc 를 지 할 수 있습니다.

> 경고 - 태그 렛은, 도크 렛 인스턴스로 지정된 MessageRetriever 를 사용해, 경고를 보고할 수 있습니다. MessageRetriever 는 Configuration 객체로부터 취득됩니다. Configuration 객체는 도크 렛으로부터 취득됩니다. 예를 들어, 태그 렛이 표준 도크 렛으로 사용하도록(듯이) 설계되고 있는 경우, Configuration 는 static 메소드인 `Standard.configuration()` 를 사용해 취득할 수 있습니다. 예로서`SimpleTaglet` 는 이와 같이 해 경고를 표시합니다. 이것은 `-tag` 옵션의 디폴트 태그 렛입니다.

Copyright © 2001-2002 Sun Microsystems, Inc. All Rights Reserved. |