jars/icu4j-4_2_1-src/src/com/ibm/icu/dev/tool/docs/ICUTaglet.java

   1 //##header J2SE15
   2 /**
   3 *******************************************************************************
   4 * Copyright (C) 2002-2009, International Business Machines Corporation and    *
   5 * others. All Rights Reserved.                                                *
   6 *******************************************************************************
   7 */
   8
   9 /**
  10  * Preprocess with com.ibm.icu.dev.tool.docs.CodeMangler to generate
  11  * either a JDK 1.4 or JDK 1.5 version.  For the 1.5 version, define
  12  * VERSION_1.5.
  13  */
  14
  15 package com.ibm.icu.dev.tool.docs;
  16
  17 import com.sun.javadoc.*;
  18 //#if defined(J2SE13) || defined(J2SE14)
  19 //##import com.sun.tools.doclets.*;
  20 //#else
  21 // jdk 1.5 contains both com.sun.tools.doclets.Taglet and
  22 // com.sun.tools.doclets.internal.toolkit.taglets.Taglet.
  23 // Their registration code casts to the second, not the first, and the
  24 // second doesn't implement the first, so if you just implement the
  25 // first, you die.
  26 import com.sun.tools.doclets.internal.toolkit.taglets.*;
  27 import com.sun.tools.doclets.internal.toolkit.taglets.Taglet;
  28 //#endif
  29
  30 import java.text.BreakIterator;
  31 import java.util.Locale;
  32 import java.util.Map;
  33
  34 public abstract class ICUTaglet implements Taglet {
  35     protected final String name;
  36     protected final int mask;
  37
  38     protected static final int MASK_FIELD = 1;
  39     protected static final int MASK_CONSTRUCTOR = 2;
  40     protected static final int MASK_METHOD = 4;
  41     protected static final int MASK_OVERVIEW = 8;
  42     protected static final int MASK_PACKAGE = 16;
  43     protected static final int MASK_TYPE = 32;
  44     protected static final int MASK_INLINE = 64;
  45
  46     protected static final int MASK_DEFAULT = 0x003f; // no inline
  47     protected static final int MASK_VALID = 0x007f; // includes inline
  48
  49     public static void register(Map taglets) {
  50         ICUInternalTaglet.register(taglets);
  51         ICUDraftTaglet.register(taglets);
  52         ICUStableTaglet.register(taglets);
  53 //#if defined(J2SE13) || defined(J2SE14)
  54 //##        ICUDeprecatedTaglet.register(taglets);
  55 //#endif
  56         ICUProvisionalTaglet.register(taglets);
  57         ICUObsoleteTaglet.register(taglets);
  58         ICUIgnoreTaglet.register(taglets);
  59     }
  60
  61     protected ICUTaglet(String name, int mask) {
  62         this.name = name;
  63         this.mask = mask & MASK_VALID;
  64     }
  65
  66     public boolean inField() {
  67         return (mask & MASK_FIELD) != 0;
  68     }
  69
  70     public boolean inConstructor() {
  71         return (mask & MASK_CONSTRUCTOR) != 0;
  72     }
  73
  74     public boolean inMethod() {
  75         return (mask & MASK_METHOD) != 0;
  76     }
  77
  78     public boolean inOverview() {
  79         return (mask & MASK_OVERVIEW) != 0;
  80     }
  81
  82     public boolean inPackage() {
  83         return (mask & MASK_PACKAGE) != 0;
  84     }
  85
  86     public boolean inType() {
  87         return (mask & MASK_TYPE) != 0;
  88     }
  89
  90     public boolean isInlineTag() {
  91         return (mask & MASK_INLINE) != 0;
  92     }
  93
  94     public String getName() {
  95         return name;
  96     }
  97
  98     public String toString(Tag tag) {
  99         return tag.text();
 100     }
 101
 102     public String toString(Tag[] tags) {
 103         if (tags != null) {
 104             if (tags.length > 1) {
 105                 String msg = "Should not have more than one ICU tag per element:\n";
 106                 for (int i = 0; i < tags.length; ++i) {
 107                     msg += "  [" + i + "] " + tags[i] + "\n";
 108                 }
 109                 throw new IllegalStateException(msg);
 110             } else if (tags.length > 0) {
 111                 return toString(tags[0]);
 112             }
 113         }
 114         return null;
 115     }
 116
 117 //#if defined(J2SE13) || defined(J2SE14)
 118 //#else
 119     public TagletOutput getTagletOutput(Tag tag, TagletWriter writer) throws IllegalArgumentException {
 120         TagletOutput out = writer.getTagletOutputInstance();
 121         out.setOutput(toString(tag));
 122         return out;
 123     }
 124
 125     public TagletOutput getTagletOutput(Doc holder, TagletWriter writer) throws IllegalArgumentException {
 126         TagletOutput out = writer.getTagletOutputInstance();
 127         Tag[] tags = holder.tags(getName());
 128         if (tags.length == 0) {
 129             return null;
 130         }
 131         out.setOutput(toString(tags[0]));
 132         return out;
 133     }
 134 //#endif
 135
 136     protected static final String STATUS = "<dt><b>Status:</b></dt>";
 137
 138     public static class ICUInternalTaglet extends ICUTaglet {
 139         private static final String NAME = "internal";
 140
 141         public static void register(Map taglets) {
 142             taglets.put(NAME, new ICUInternalTaglet());
 143         }
 144
 145         private ICUInternalTaglet() {
 146             super(NAME, MASK_DEFAULT);
 147         }
 148
 149         public String toString(Tag tag) {
 150             return STATUS + "<dd><em>Internal</em>. <font color='red'>This API is <em>ICU internal only</em>.</font></dd>";
 151         }
 152     }
 153
 154     public static class ICUDraftTaglet extends ICUTaglet {
 155         private static final String NAME = "draft";
 156
 157         public static void register(Map taglets) {
 158             taglets.put(NAME, new ICUDraftTaglet());
 159         }
 160
 161         private ICUDraftTaglet() {
 162             super(NAME, MASK_DEFAULT);
 163         }
 164
 165         public String toString(Tag tag) {
 166             String text = tag.text();
 167             if (text.length() == 0) {
 168                 System.err.println("Warning: empty draft tag");
 169             }
 170             return STATUS + "<dd>Draft " + tag.text() + ".</dd>";
 171         }
 172     }
 173
 174     public static class ICUStableTaglet extends ICUTaglet {
 175         private static final String NAME = "stable";
 176
 177         public static void register(Map taglets) {
 178             taglets.put(NAME, new ICUStableTaglet());
 179         }
 180
 181         private ICUStableTaglet() {
 182             super(NAME, MASK_DEFAULT);
 183         }
 184
 185         public String toString(Tag tag) {
 186             String text = tag.text();
 187             if (text.length() > 0) {
 188                 return STATUS + "<dd>Stable " + text + ".</dd>";
 189             } else {
 190                 return STATUS + "<dd>Stable.</dd>";
 191             }
 192         }
 193     }
 194 //#if defined(J2SE13) || defined(J2SE14)
 195 //##    /*
 196 //##     * sigh, in JDK 1.5 we can't override the standard deprecated taglet
 197 //##     * so easily.  I'm not impressed with the javadoc code.
 198 //##     */
 199 //##    public static class ICUDeprecatedTaglet extends ICUTaglet {
 200 //##        private static final String NAME = "deprecated";
 201 //##
 202 //##        public static void register(Map taglets) {
 203 //##            taglets.remove(NAME); // override standard deprecated taglet
 204 //##            taglets.put(NAME, new ICUDeprecatedTaglet());
 205 //##        }
 206 //##
 207 //##        private ICUDeprecatedTaglet() {
 208 //##            super(NAME, MASK_DEFAULT);
 209 //##        }
 210 //##
 211 //##        public String toString(Tag tag) {
 212 //##            BreakIterator bi = BreakIterator.getSentenceInstance(Locale.US);
 213 //##            String text = tag.text();
 214 //##            bi.setText(text);
 215 //##            int first = bi.first();
 216 //##            int next = bi.next();
 217 //##            if (first == -1 || next == -1) {
 218 //##                System.err.println("Warning: bad deprecated tag '" + text + "'");
 219 //##                return "<dd><em>Note</em>. " + text + "</dd>";
 220 //##            } else {
 221 //##                if ("This API is ICU internal only.".equals(text)) {
 222 //##                    return null;
 223 //##                }
 224 //##                return "<dd><em>Note, " + text.substring(first, next) + "</em>. " + text.substring(next) + "</dd>";
 225 //##            }
 226 //##        }
 227 //##    }
 228 //#endif
 229
 230     public static class ICUProvisionalTaglet extends ICUTaglet {
 231         private static final String NAME = "provisional";
 232
 233         public static void register(Map taglets) {
 234             taglets.remove(NAME); // override standard deprecated taglet
 235             taglets.put(NAME, new ICUProvisionalTaglet());
 236         }
 237
 238         private ICUProvisionalTaglet() {
 239             super(NAME, MASK_DEFAULT);
 240         }
 241
 242         public String toString(Tag tag) {
 243             return null;
 244         }
 245     }
 246
 247     public static class ICUObsoleteTaglet extends ICUTaglet {
 248         private static final String NAME = "obsolete";
 249
 250         public static void register(Map taglets) {
 251             taglets.put(NAME, new ICUObsoleteTaglet());
 252         }
 253
 254         private ICUObsoleteTaglet() {
 255             super(NAME, MASK_DEFAULT);
 256         }
 257
 258         public String toString(Tag tag) {
 259             BreakIterator bi = BreakIterator.getSentenceInstance(Locale.US);
 260             String text = tag.text();
 261             bi.setText(text);
 262             int first = bi.first();
 263             int next = bi.next();
 264             if (text.length() == 0) {
 265                 first = next = 0;
 266             }
 267             return STATUS + "<dd><em>Obsolete.</em> <font color='red'>Will be removed in " + text.substring(first, next) + "</font>. " + text.substring(next) + "</dd>";
 268
 269         }
 270     }
 271
 272     public static class ICUIgnoreTaglet extends ICUTaglet {
 273         private static ICUTaglet singleton;
 274
 275         public static void register(Map taglets) {
 276             if (singleton == null) {
 277                 singleton = new ICUIgnoreTaglet();
 278             }
 279             taglets.put("bug", singleton);
 280             taglets.put("test", singleton);
 281             taglets.put("summary", singleton);
 282         }
 283
 284         private ICUIgnoreTaglet() {
 285             super(".ignore", MASK_DEFAULT);
 286         }
 287
 288         public String toString(Tag tag) {
 289             return null;
 290         }
 291     }
 292 }