001/*license*\
002   Codelet: Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com)
003
004   This software is dual-licensed under the:
005   - Lesser General Public License (LGPL) version 3.0 or, at your option, any later version;
006   - Apache Software License (ASL) version 2.0.
007
008   Either license may be applied at your discretion. More information may be found at
009   - http://en.wikipedia.org/wiki/Multi-licensing.
010
011   The text of both licenses is available in the root directory of this project, under the names "LICENSE_lgpl-3.0.txt" and "LICENSE_asl-2.0.txt". The latest copies may be downloaded at:
012   - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt
013   - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt
014\*license*/
015package  com.github.aliteralmind.codelet.taglet;
016   import  com.github.aliteralmind.codelet.CodeletBootstrap;
017   import  com.github.aliteralmind.codelet.CodeletType;
018   import  com.sun.javadoc.Tag;
019   import  com.sun.tools.doclets.Taglet;
020   import  java.util.Map;
021/**
022   <P>Inline JavaDoc taglet for displaying the contents of a plain-text file (usually one associated to an example code, such as its input). This tag can be used in any kind of {@link com.sun.javadoc.Doc}.</P>
023
024   <P>The only custom code in this class is the {@link #NAME} field and {@link #toString(Tag) toString} function.</P>
025
026   <P>Jamie Ho's <A HREF="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/taglet/overview.html#inlineexample">UnderlineTaglet</A> was the template used to create this file.</P>
027
028   @since  0.1.0
029   @author  Copyright (C) 2014, Jeff Epstein ({@code aliteralmind __DASH__ github __AT__ yahoo __DOT__ com}), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. <A HREF="http://codelet.aliteralmind.com">{@code http://codelet.aliteralmind.com}</A>, <A HREF="https://github.com/aliteralmind/codelet">{@code https://github.com/aliteralmind/codelet}</A>.
030 **/
031public class FileTextletTaglet implements Taglet {
032   /*
033      To avoid configuration from being loaded repeatedly.
034    */
035   private static final CodeletBootstrap BOOTSTRAP = CodeletBootstrap.INSTANCE;
036   /**
037      <P>The name of this taglet, which appears immediately after the <CODE>&#123;&#64;</CODE>--Equal to
038      <BR> &nbsp; &nbsp; <CODE>{@link com.github.aliteralmind.codelet.CodeletType CodeletType}.{@link com.github.aliteralmind.codelet.CodeletType#FILE_TEXT FILE_TEXT}.{@link com.github.aliteralmind.codelet.CodeletType#getName() getName}()</CODE></P>
039    **/
040    public static final String NAME = CodeletType.FILE_TEXT.getName();
041
042    /**
043     * Return the name of this custom tag.
044
045     @return  #NAME
046     */
047    public String getName() {
048        return NAME;
049    }
050
051    /**
052     * @return true since this tag can be used in a field
053     *         doc comment
054     */
055    public boolean inField() {
056        return true;
057    }
058
059    /**
060     * @return true since this tag can be used in a constructor
061     *         doc comment
062     */
063    public boolean inConstructor() {
064        return true;
065    }
066
067    /**
068     * @return true since this tag can be used in a method
069     *         doc comment
070     */
071    public boolean inMethod() {
072        return true;
073    }
074
075    /**
076     * @return true since this tag can be used in an overview
077     *         doc comment
078     */
079    public boolean inOverview() {
080        return true;
081    }
082
083    /**
084     * @return true since this tag can be used in a package
085     *         doc comment
086     */
087    public boolean inPackage() {
088        return true;
089    }
090
091    /**
092     * @return true since this
093     */
094    public boolean inType() {
095        return false;
096    }
097
098    /**
099     * Will return true since this is an inline tag.
100     * @return true since this is an inline tag.
101     */
102
103    public boolean isInlineTag() {
104        return true;
105    }
106   /**
107      <P>Register this Taglet.</P>
108
109      <P>Equal to
110      <BR> &nbsp; &nbsp; <CODE>{@link ComSunJavaDocUtil}.{@link ComSunJavaDocUtil#registerNewTagletInstance(Taglet, Map) registerNewTagletInstance}(new {@link #FileTextletTaglet() FileTextletTaglet}(), taglet_map)</CODE></P>
111    */
112   @SuppressWarnings({"unchecked", "rawtypes"})
113   public static void register(Map taglet_map) {
114      ComSunJavaDocUtil.registerNewTagletInstance(new FileTextletTaglet(), taglet_map);
115   }
116
117    /**
118     * Given the <code>Tag</code> representation of this custom
119     * tag, return its string representation.
120     * @param tag he <code>Tag</code> representation of this custom tag.
121      @return  <CODE>{@link com.github.aliteralmind.codelet.taglet.CodletComSunJavadocTagProcessor CodletComSunJavadocTagProcessor}.{@link com.github.aliteralmind.codelet.taglet.CodletComSunJavadocTagProcessor#get(Tag) get}(tag)</CODE>
122     */
123    public String toString(Tag tag) {
124       return  CodletComSunJavadocTagProcessor.get(tag);
125    }
126
127    /**
128     * This method should not be called since arrays of inline tags do not
129     * exist.  Method {@link #toString(Tag)} should be used to convert this
130     * inline tag to a string.
131     * @param tags the array of <code>Tag</code>s representing of this custom tag.
132     */
133    public String toString(Tag[] tags) {
134        return null;
135    }
136}