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

# 「태그 렛의 개요」

## 목차

- 태그 렛 API
- 태그 렛의 기술
- 예 - 단순한 블록 태그 렛
- 예 - 인 라인 태그를 처리하는 블록 태그 렛
- 예 - 인 라인 태그 렛
- 에러 및 경고의 처리

## 태그 렛 API

태그 렛은, JavaTM 프로그램 언어로 기술한 프로그램이며, 태그 렛 API 를 구현하고 있습니다. 태그 렛은, 블록 태그 (예를 들어 `@todo`)와 인 라인 태그 (예를 들어 `{@underline}`)의 양쪽 모두를 지원합니다. (「블록 태그와 인 라인 태그」를 참조해 주세요. ) 태그 렛 API 는, 다음의 1 개의 인터페이스와 2 개의 abstract 클래스로 구성되어 있습니다.

- 태그 렛 API
  `Taglet` 인터페이스
    인 라인 태그를 지원할 필요가 없는 블록 태그 렛을 기술하는 경우, 또는 일반의 인 라인 태그를 기술하는 경우에 구현합니다.
  `BaseExecutableMemberTaglet` 클래스
    인 라인 태그를 지원하는 블록 태그 렛을 기술하는 경우에 상속합니다.
  `BaseInlineTaglet` 클래스
    HtmlStandardWriter 나 doc 객체에 액세스 할 필요가 있는 인 라인 태그를 기술하는 경우에 상속합니다.

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

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

## 태그 렛의 기술

다음중 어느 쪽의 종류의 태그 렛을 기술할까를 선택해, 적절한 인터페이스를 구현하는지, 적절한 abstract 클래스를 상속합니다.

- 블록 태그 렛
  - 블록 태그 렛 인 라인 태그를 지원하는 경우 - `BaseExecutableMemberTaglet` 를 상속
  - 인 라인 태그를 지원하지 않는 경우 - `Taglet` 를 구현 인 라인 태그 렛
- 인 라인 태그 렛
  - 일반의 인 라인 태그 - `Taglet` 를 구현
  - HtmlStandardWriter 또는 Doc 객체에 액세스 할 필요가 있는 경우 - `BaseInlineTag` 를 상속

`BaseExecutableMemberTaglet` 클래스는,`Taglet` 를 확장한 것으로, 인 라인 태그를 지원하기 위한 추가 기능을 제공하고 있습니다. 이 클래스는,`{@link}` 나 `{@docroot}` 라고 하는 표준 인 라인 태그와 사용자가 작성하는 커스텀 인 라인 태그의 양쪽 모두를 지원합니다.

`HtmlStandardWriter` 또는 `Doc` 객체에 액세스 할 필요가 있는 인 라인 태그를 기술하는 경우에는,`BaseInlineTag` 를 상속할 필요가 있습니다. 예를 들어,`{@value}` 인 라인 태그에서는, 필드로부터 정수치를 취득하기 위해서 `Doc` 객체가 필요합니다. 대부분의 태그는, 도크 렛의 에러 보고 메소드를 사용해 에러를 보고하기 위해서(때문에) `HtmlStandardWriter` 만을 필요로 합니다.

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

1. 태그 렛이 되는 Java 프로그램을 기술합니다. 기술하는 태그 렛에 적절한 import 문을 짜넣습니다. 예를 들어,`BaseExecutableMemberTaglet` 를 확장하는 경우이면, 다음과 같은 import 문이 필요합니다.

       import com.sun.tools.doclets.Taglet;                                        // Taglet API
       import com.sun.tools.doclets.standard.tags.BaseExecutableMemberTaglet;      // For inline tags
       import com.sun.tools.doclets.standard.HtmlStandardWriter;                   // For error reporting???
       import com.sun.javadoc. *;                                                   // Doclet API
       import java.util.Map;                                                       // Used in register(Map)

   `toString(Tag)` 로 사용되는 `Tag` 인터페이스는, 도크 렛 API 의 일부입니다.

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

           public static void register(Map tagletMap)

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

           toString(Doc, HtmlStandardWriter)

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

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

4. `-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

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

YET TO UPDATE BELOW HERE !!!!!!!!!!!!!!

## 예 - 단순한 블록 태그 렛

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

> 도크 렛을 실행하려면 ,`-tagletpath` 및 `-taglet` 옵션을 지정합니다. `ToDoTaglet.class` 이 `/home/user/taglet` 에 있어,`@todo` 태그가 `Test.java` 파일내에 있다고 하면(자), 커멘드는 다음과 같이 됩니다.

>     % javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet . /Test.java

> 파일 `Test.java` 에 다음과 같은 다큐멘테이션 코멘트가 포함되어 있다고 하면(자),

>         /**
>          * @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}` 태그에 조우했을 때, 텍스트를 어떻게 출력에 삽입할까를 결정합니다.

## 예 - 인 라인 태그를 처리하는 블록 태그 렛

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

> 도크 렛을 실행하려면 ,`-tagletpath` 및 `-taglet` 옵션을 지정합니다. `ToDoTaglet.class` 이 `/home/user/taglet` 에 있어,`@todo` 태그가 `Test.java` 파일내에 있다고 하면(자), 커멘드는 다음과 같이 됩니다.

>     % javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet . /Test.java

> 파일 `Test.java` 에 다음과 같은 다큐멘테이션 코멘트가 포함되어 있다고 하면(자),

>         /**
>          * @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}` 태그에 조우했을 때, 텍스트를 어떻게 출력에 삽입할까를 결정합니다.

## 예 - 인 라인 태그 렛

> 블록 태그와는 달라, 커스텀인 라인 태그는, 태그 렛을 사용해서만 구현할 수 있습니다. 즉,`-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 Sun Microsystems, Inc. All Rights Reserved. |