001    /*
002     * Copyright 2006 Google Inc.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005     * use this file except in compliance with the License. You may obtain a copy of
006     * the License at
007     * 
008     * http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012     * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013     * License for the specific language governing permissions and limitations under
014     * the License.
015     * 
016     * IMPLEMENTATION NOTES
017     * 
018     * This is a useful way to unify various forms of metadata so that clients don't
019     * have to be brittle with respect to Java language versions. For example, this
020     * mechanism exposes the tag "gwt.typeArgs" in a way that is independent of
021     * whether a doc comment was used or (in the future) a concrete instantiation of
022     * a generic type was used. The same idea could be useful for to exposing
023     * attributes as metadata.
024     */
025    package com.google.gwt.core.ext.typeinfo;
026    
027    /**
028     * Manages doc comment metadata for an AST item. The structure of the metadata
029     * attempts to mirror the way in which tags and values were originally declared.
030     * 
031     * <p>
032     * For example, for the following declaration
033     * 
034     * <pre>
035     * /**
036     *  * @myTag value1 value2
037     *  * @myTag value3 value4
038     *  * ... 
039     * </pre>
040     * 
041     * a call to <code>getMetaData("myTag")</code> would return this array of
042     * string arrays
043     * 
044     * <pre>
045     *[0][0] = value1
046     *[0][1] = value2
047     *[1][0] = value3
048     *[1][1] = value4
049     * </pre>
050     * 
051     * </p>
052     */
053    public interface HasMetaData {
054      /**
055       * Gets each list of metadata for the specified tag name.
056       */
057      String[][] getMetaData(String tagName);
058    
059      /**
060       * Gets the name of available metadata tags.
061       */
062      String[] getMetaDataTags();
063    
064      /**
065       * Adds additional metadata.
066       */
067      void addMetaData(String tagName, String[] values);
068    }