ITEEDU

Java Gossip: 要求为 API 文件的一部份 - Documented

在制作JavaDoc文件时，预设上并不会将Annotation的数据加入到文件中，例如您设计了以下的 Annotation型别：

Debug.java

package onlyfun.caterpillar;
public @interface Debug {} 

然后将之用在以下的程序中：

SomeObject.java

package onlyfun.caterpillar;
public class SomeObject {
	@Debug
	public void doSomething() {?
		// ....?
	}
}

您可以试着产生Java Doc文件，文件中并不会有Annotation的讯息。


Annotation用于为程序代码作批注，有时它包括了重要的讯息，您也许会想要使用者制作文件的同时，也一并将Annotation的讯息加入，您可以 使用java.lang.annotation.Documented，例如：

Debug.java

package onlyfun.caterpillar;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Debug {}

使用java.lang.annotation.Documented时，同时的您必须使用Retention指定编译器将讯 息加入class档案，并可以由VM读取，即设定RetentionPolicy为RUNTIME，接着您可以重新产生Java Doc文件，这次可以看到文件中包括了@Debug的讯息。