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}