ICU-2103 added Taglet support to format ICU4J tags, clean up build.xml to verify JDK1.4 before compiling tool/docs

X-SVN-Rev: 10433

icu4j/build.xml

@@ -6,8 +6,8 @@
 *******************************************************************************
 *
 * $Source: /xsrl/Nsvn/icu/icu4j/build.xml,v $
-* $Date: 2002/12/02 20:06:32 $
-* $Revision: 1.58 $
+* $Date: 2002/12/03 06:27:43 $
+* $Revision: 1.59 $
 *
 *******************************************************************************
 * This is the ant build file for ICU4J.  See readme.html for more information.
@@ -43,28 +43,28 @@
     </target>
     <!-- ### end clover setup ### -->
 
-    <target name="hack1">
+    <target name="anthack1">
         <!-- It's a real pain to set properties conditionally.
           Ant 1.5 isn't really any better than 1.4, in fact 1.5 enforces that
           properties are write-once so you can't even set a default and then
           override it, which we used to do for Ant 1.4. -->
-        <condition property="version.1.4.or.higher">
+        <condition property="version.1.4">
         <or>
 	    <equals arg1="${ant.java.version}" arg2="1.4"/>
         </or>
         </condition>
 
 	<condition property="doc.params"
-	    value="-breakiterator -tag draft:a:&quot;Draft&quot; -tag internal:X:&quot;Internal&quot; -tag stable:a:&quot;Stable&quot;">
-            <equals arg1="${version.1.4.or.higher}" arg2="true"/>
+	    value="-breakiterator -use -tagletpath ./classes -taglet com.ibm.icu.dev.tool.docs.ICUTaglet">
+            <equals arg1="${version.1.4}" arg2="true"/>
 	</condition>
     </target>
 
-    <target name="hack2" unless="doc.params">
+    <target name="anthack2" unless="doc.params">
         <property name="doc.params" value=""/>
     </target>
 
-    <target name="init" depends="hack1, hack2">
+    <target name="init">
         <tstamp/>
         <property name="src.dir" value="src"/>
         <property name="build.dir" value="classes"/>
@@ -94,7 +94,6 @@
         <echo message="java version: ${java.version}"/>
         <echo message="ant java version: ${ant.java.version}"/>
         <echo message="${ant.version}"/>
-        <echo message="doc params: ${doc.params}"/>
     </target>
 
     <!-- build everything but dist-related stuff -->
@@ -142,8 +141,8 @@
             debug="on" deprecation="off"/>
     </target>
 
-    <target name="tools" depends="core">
-        <javac includes="com/ibm/icu/dev/tool/**/*.java"
+    <target name="one4tools" depends="anthack1,anthack2" if="version.1.4">
+        <javac includes="com/ibm/icu/dev/tool/docs/*.java"
             excludes="**/CVS/**/*"
     	    srcdir="${src.dir}"
     	    destdir="${build.dir}"
@@ -151,7 +150,17 @@
             debug="on" deprecation="off"/>
     </target>
 
-    <target name="docs" depends="init">
+    <target name="tools" depends="core,one4tools">
+        <javac includes="com/ibm/icu/dev/tool/**/*.java"
+            excludes="com/ibm/icu/dev/tool/docs/*,**/CVS/**/*"
+    	    srcdir="${src.dir}"
+    	    destdir="${build.dir}"
+    	    classpathref="build.classpath"
+            debug="on" deprecation="off"/>
+    </target>
+
+    <target name="docs" depends="anthack1,anthack2,tools">
+        <echo message="doc params: ${doc.params}"/>
         <mkdir dir="${doc.dir}"/>
         <javadoc packagenames="com.ibm.icu.lang,com.ibm.icu.dev.tool.translit,com.ibm.icu.text,com.ibm.icu.impl.data,com.ibm.icu.dev.tool.compression,com.ibm.icu.dev.tool.normalizer,com.ibm.icu.util,com.ibm.icu.dev.tool.rbbi,com.ibm.icu.math,com.ibm.richtext.textlayout,com.ibm.richtext.textlayout.attributes,com.ibm.richtext.awtui,com.ibm.richtext.print,com.ibm.richtext.styledtext,com.ibm.richtext.swingui,com.ibm.richtext.textapps,com.ibm.richtext.textformat,com.ibm.richtext.textpanel,com.ibm.richtext.uiimpl,com.ibm.richtext.uiimpl.resources,com.ibm.richtext.textapps.resources"
             sourcepath="${src.dir}"
@@ -276,9 +285,12 @@
 	</java>
     </target>
 
+    <target name="_requires14" unless="version.1.4">
+        <echo message="One of your targets requires JAVA_HOME to be set to JDK version 1.4"/>
+    </target>
 
-    <target name="checktags" depends="tools">
-        <echo message="Execute with a JDK that provides access to com.sun.* packages"/>
+    <target name="_checktags" depends="anthack1,anthack2,tools" if="version.1.4">
+        <echo message="doc params: ${doc.params}"/>
         <javadoc sourcepath="${src.dir}" 
                  packagenames="com.ibm.icu.*"
                  excludepackagenames="com.ibm.icu.dev.*,com.ibm.icu.impl.*"
@@ -290,6 +302,8 @@
         </javadoc>
     </target>
 
+    <target name="checktags" depends="anthack1,anthack2,_requires14,_checktags"/>
+
     <target name="clean" depends="init">
         <delete dir="${build.dir}"/>
         <delete dir="${doc.dir}"/>

icu4j/src/com/ibm/icu/dev/tool/docs/CheckTags.java

@@ -180,7 +180,7 @@ public class CheckTags {
 
     static final String[] tagKinds = {
         "@internal", "@draft", "@stable", "@since", "@deprecated", "@author", "@see", "@version",
-        "@param", "@return", "@throws, @obsolete"
+        "@param", "@return", "@throws, @obsolete, @exception"
     };
 
     static final int UNKNOWN = -1;
@@ -196,6 +196,7 @@ public class CheckTags {
     static final int RETURN = 9;
     static final int THROWS = 10;
     static final int OBSOLETE = 11;
+    static final int EXCEPTION = 12;
 
     static int tagKindIndex(String kind) {
         for (int i = 0; i < tagKinds.length; ++i) {
@@ -237,8 +238,8 @@ public class CheckTags {
     }
 
     void tagErr(Tag tag) {
-        // errln(tag.toString() + " [" + tag.position() + "]");
-        errln(tag.toString()); // comment out since JDK 1.3.0 doesn't define tag.position()
+        // Tag.position() requires JDK 1.4, build.xml tests for this
+        errln(tag.toString() + " [" + tag.position() + "]");
     }
 
     void doDocs(ProgramElementDoc[] docs, String header, boolean reportError) {
@@ -314,6 +315,9 @@ public class CheckTags {
                 tagErr(tag);
                 break;
 
+            case EXCEPTION:
+                logln("You really ought to use @throws, you know... :-)");
+
             case AUTHOR:
             case SEE:
             case PARAM:

icu4j/src/com/ibm/icu/dev/tool/docs/ICUTaglet.java

@@ -0,0 +1,195 @@
+package com.ibm.icu.dev.tool.docs;
+
+import com.sun.javadoc.*;
+import com.sun.tools.doclets.*;
+
+import java.text.BreakIterator;
+import java.util.Locale;
+import java.util.Map;
+
+public abstract class ICUTaglet implements Taglet {
+    protected final String name;
+    protected final int mask;
+
+    protected static final int MASK_FIELD = 1;
+    protected static final int MASK_CONSTRUCTOR = 2;
+    protected static final int MASK_METHOD = 4;
+    protected static final int MASK_OVERVIEW = 8;
+    protected static final int MASK_PACKAGE = 16;
+    protected static final int MASK_TYPE = 32;
+    protected static final int MASK_INLINE = 64;
+
+    protected static final int MASK_DEFAULT = 0x003f; // no inline
+    protected static final int MASK_VALID = 0x007f; // includes inline
+
+    public static void register(Map taglets) {
+        ICUInternalTaglet.register(taglets);
+        ICUDraftTaglet.register(taglets);
+        ICUStableTaglet.register(taglets);
+        ICUDeprecatedTaglet.register(taglets);
+        ICUObsoleteTaglet.register(taglets);
+    }
+
+    protected ICUTaglet(String name, int mask) {
+        this.name = name;
+        this.mask = mask & MASK_VALID;
+    }
+
+    public boolean inField() {
+        return (mask & MASK_FIELD) != 0;
+    }
+
+    public boolean inConstructor() {
+        return (mask & MASK_FIELD) != 0;
+    }
+
+    public boolean inMethod() {
+        return (mask & MASK_FIELD) != 0;
+    }
+
+    public boolean inOverview() {
+        return (mask & MASK_FIELD) != 0;
+    }
+
+    public boolean inPackage() {
+        return (mask & MASK_FIELD) != 0;
+    }
+
+    public boolean inType() {
+        return (mask & MASK_FIELD) != 0;
+    }
+
+    public boolean isInlineTag() {
+        return (mask & MASK_FIELD) != 0;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public String toString(Tag tag) {
+        return tag.text();
+    }
+
+    public String toString(Tag[] tags) {
+        if (tags != null) {
+            if (tags.length > 1) {
+                String msg = "Should not have more than one ICU tag per element:\n";
+                for (int i = 0; i < tags.length; ++i) {
+                    msg += "  [" + i + "] " + tags[i] + "\n";
+                }
+                throw new InternalError(msg);
+            } else if (tags.length > 0) {
+                return toString(tags[0]);
+            }
+        }
+        return null;
+    }
+
+    protected static final String STATUS = "<dt><b>Status:</b></dt>";
+
+    public static class ICUInternalTaglet extends ICUTaglet {
+        private static final String NAME = "internal";
+
+        public static void register(Map taglets) {
+            taglets.put(NAME, new ICUInternalTaglet());
+        }
+
+        private ICUInternalTaglet() {
+            super(NAME, MASK_DEFAULT);
+        }
+
+        public String toString(Tag tag) {
+            return STATUS + "<dd><em>Internal</em>. <font color='red'>This API is <em>Internal Only</em> and can change at any time.</font></dd>";
+        }
+    }
+
+    public static class ICUDraftTaglet extends ICUTaglet {
+        private static final String NAME = "draft";
+
+        public static void register(Map taglets) {
+            taglets.put(NAME, new ICUDraftTaglet());
+        }
+
+        private ICUDraftTaglet() {
+            super(NAME, MASK_DEFAULT);
+        }
+
+        public String toString(Tag tag) {
+            String text = tag.text();
+            if (text.length() == 0) {
+                System.err.println("Warning: empty draft tag");
+            }
+            return STATUS + "<dd>Draft " + tag.text() + ".</dd>";
+        }
+    }
+
+    public static class ICUStableTaglet extends ICUTaglet {
+        private static final String NAME = "stable";
+
+        public static void register(Map taglets) {
+            taglets.put(NAME, new ICUStableTaglet());
+        }
+
+        private ICUStableTaglet() {
+            super(NAME, MASK_DEFAULT);
+        }
+
+        public String toString(Tag tag) {
+            String text = tag.text();
+            if (text.length() > 0) {
+                return STATUS + "<dd>Stable " + text + ".</dd>";
+            } else {
+                return STATUS + "<dd>Stable.</dd>";
+            }
+        }
+    }
+
+    public static class ICUDeprecatedTaglet extends ICUTaglet {
+        private static final String NAME = "deprecated";
+
+        public static void register(Map taglets) {
+            taglets.put(NAME, new ICUDeprecatedTaglet());
+        }
+
+        private ICUDeprecatedTaglet() {
+            super(NAME, MASK_DEFAULT);
+        }
+
+        public String toString(Tag tag) {
+            BreakIterator bi = BreakIterator.getSentenceInstance(Locale.US);
+            String text = tag.text();
+            bi.setText(text);
+            int first = bi.first();
+            int next = bi.next();
+            if (first == -1 || next == -1) {
+                System.err.println("Warning: bad deprecated tag '" + text + "'");
+                return STATUS + "<dd><em>Deprecated</em>. " + text + "</dd>";
+            } else {
+                return STATUS + "<dd><em>Deprecated in " + text.substring(first, next) + "</em>. " + text.substring(next) + "</dd>";
+            }
+        }
+    }
+
+    public static class ICUObsoleteTaglet extends ICUTaglet {
+        private static final String NAME = "obsolete";
+
+        public static void register(Map taglets) {
+            taglets.put(NAME, new ICUObsoleteTaglet());
+        }
+
+        private ICUObsoleteTaglet() {
+            super(NAME, MASK_DEFAULT);
+        }
+
+        public String toString(Tag tag) {
+            BreakIterator bi = BreakIterator.getSentenceInstance(Locale.US);
+            String text = tag.text();
+            bi.setText(text);
+            int first = bi.first();
+            int next = bi.next();
+            return STATUS + "<dd><em>Obsolete.</em> <font color='red'>Will be removed in " + text.substring(first, next) + "</font>. " + text.substring(next) + "</dd>";
+
+        }
+    }
+}