package-info.java revision 3578:b56896d30c0f
113394Swpaul/* 213394Swpaul * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved. 313394Swpaul * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 413394Swpaul * 513394Swpaul * This code is free software; you can redistribute it and/or modify it 613394Swpaul * under the terms of the GNU General Public License version 2 only, as 713394Swpaul * published by the Free Software Foundation. Oracle designates this 813394Swpaul * particular file as subject to the "Classpath" exception as provided 913394Swpaul * by Oracle in the LICENSE file that accompanied this code. 1013394Swpaul * 1113394Swpaul * This code is distributed in the hope that it will be useful, but WITHOUT 1213394Swpaul * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1313394Swpaul * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1413394Swpaul * version 2 for more details (a copy is included in the LICENSE file that 1513394Swpaul * accompanied this code). 1613394Swpaul * 1713394Swpaul * You should have received a copy of the GNU General Public License version 1813394Swpaul * 2 along with this work; if not, write to the Free Software Foundation, 1913394Swpaul * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2013394Swpaul * 2113394Swpaul * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2213394Swpaul * or visit www.oracle.com if you need additional information or have any 2313394Swpaul * questions. 2413394Swpaul */ 2513394Swpaul 2613394Swpaul/** 2713394Swpaul<p style="font-style: italic; font-size:larger"> 2813394Swpaul<b>Note:</b> The declarations in this package have been superseded by those 2913394Swpaulin the package {@code jdk.javadoc.doclet}. 3013394SwpaulFor more information, see the <i>Migration Guide</i> in the documentation for that package. 3113394Swpaul</p> 3213394Swpaul 3330911ScharnierThe Doclet API (also called the Javadoc API) provides a mechanism 3430911Scharnierfor clients to inspect the source-level structure of programs and 3550479Speterlibraries, including javadoc comments embedded in the source. 3630911ScharnierThis is useful for documentation, program checking, automatic 3730911Scharniercode generation and many other tools. 3830911Scharnier<p> 3930911Scharnier 4013394SwpaulDoclets are invoked by javadoc and use this API to write out 4113394Swpaulprogram information to files. For example, the standard doclet is called 4213394Swpaulby default and writes out documentation to HTML files. 4313394Swpaul<p> 4430911Scharnier 4513394SwpaulThe invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class 4613394Swpaul-- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: 4713394Swpaul<pre> 4813394Swpaul public static boolean <b>start</b>(RootDoc root) 4913394Swpaul</pre> 5013394SwpaulThe {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure 5113394Swpaulinformation. From this root all other program structure 5213394Swpaulinformation can be extracted. 5313394Swpaul<p> 5413394Swpaul 5513394Swpaul<a name="terminology"></a> 5613394Swpaul<h3>Terminology</h3> 5713394Swpaul 5813394Swpaul<a name="included"></a> 5913394SwpaulWhen calling javadoc, you pass in package names and source file names -- 6013394Swpaulthese are called the <em>specified</em> packages and classes. 6113394SwpaulYou also pass in Javadoc options; the <em>access control</em> Javadoc options 6213394Swpaul({@code -public}, {@code -protected}, {@code -package}, 6313394Swpauland {@code -private}) filter program elements, producing a 6413394Swpaulresult set, called the <em>included</em> set, or "documented" set. 6513394Swpaul(The unfiltered set is also available through 6613394Swpaul{@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) 6713394Swpaul<p> 6813394Swpaul 6913394Swpaul<a name="class"></a> 7013394SwpaulThroughout this API, the term <em>class</em> is normally a 7113799Swpaulshorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, 7213394Swpaul{@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and 7313394Swpaul{@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. 7413394SwpaulIn only a couple of other places, it means "class, as opposed to interface", 7513394Swpaulas in: {@link com.sun.javadoc.Doc#isClass()}. 7613394SwpaulIn the second sense, this API calls out four kinds of classes: 7713394Swpaul{@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, 7813394Swpaul{@linkplain com.sun.javadoc.Doc#isEnum() enums}, 7913394Swpaul{@linkplain com.sun.javadoc.Doc#isError() errors} and 8013394Swpaul{@linkplain com.sun.javadoc.Doc#isException() exceptions}. 8113394SwpaulThroughout the API, the detailed description of each program element 8213394Swpauldescribes explicitly which meaning is being used. 8313394Swpaul<p> 8413394Swpaul 8513394Swpaul<a name="qualified"></a> 8613394SwpaulA <em>qualified</em> class or interface name is one that has its package 8713394Swpaulname prepended to it, such as {@code java.lang.String}. A non-qualified 8813394Swpaulname has no package name, such as {@code String}. 8913394Swpaul<p> 9013394Swpaul 9113394Swpaul<a name="example"></a> 9213394Swpaul<h3>Example</h3> 9313394Swpaul 9490297SdesThe following is an example doclet that 9513394Swpauldisplays information in the {@code @param} tags of the processed 9613394Swpaulclasses: 9713394Swpaul<pre> 9813394Swpaulimport com.sun.javadoc.*; 9913394Swpaul 10013394Swpaulpublic class ListParams extends <span style="color:red" >Doclet</span> { 10113394Swpaul 10213394Swpaul public static boolean start(<span style="color:red" >RootDoc</span> root) { 10313394Swpaul <span style="color:red" >ClassDoc</span>[] classes = root.<span style="color:red" >classes</span>(); 10413394Swpaul for (int i = 0; i < classes.length; ++i) { 10513394Swpaul <span style="color:red" >ClassDoc</span> cd = classes[i]; 10613394Swpaul printMembers(cd.<span style="color:red" >constructors</span>()); 10713394Swpaul printMembers(cd.<span style="color:red" >methods</span>()); 10813394Swpaul } 10913394Swpaul return true; 11013394Swpaul } 11113394Swpaul 11213394Swpaul static void printMembers(<span style="color:red" >ExecutableMemberDoc</span>[] mems) { 11313394Swpaul for (int i = 0; i < mems.length; ++i) { 11490297Sdes <span style="color:red" >ParamTag</span>[] params = mems[i].<span style="color:red" >paramTags</span>(); 11513394Swpaul System.out.println(mems[i].<span style="color:red" >qualifiedName</span>()); 11613394Swpaul for (int j = 0; j < params.length; ++j) { 11713394Swpaul System.out.println(" " + params[j].<span style="color:red" >parameterName</span>() 11813394Swpaul + " - " + params[j].<span style="color:red" >parameterComment</span>()); 11913394Swpaul } 12013394Swpaul } 12113394Swpaul } 12213394Swpaul} 12313394Swpaul</pre> 12413394SwpaulInterfaces and methods from the Javadoc API are marked in 12530911Scharnier<span style="color:red" >red</span>. 12613394Swpaul{@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies 12713394Swpaulthe invocation interface for doclets, 12830911Scharnier{@link com.sun.javadoc.Doclet Doclet} holds class or interface information, 12913394Swpaul{@link com.sun.javadoc.ExecutableMemberDoc} is a 13013394Swpaulsuperinterface of {@link com.sun.javadoc.MethodDoc} and 13113394Swpaul{@link com.sun.javadoc.ConstructorDoc}, 13290297Sdesand {@link com.sun.javadoc.ParamTag} holds information 13313394Swpaulfrom "{@code @param}" tags. 13413394Swpaul<p> 13513394SwpaulThis doclet when invoked with a command line like: 13613394Swpaul<pre> 13713394Swpaul javadoc -doclet ListParams -sourcepath <source-location> java.util 13813394Swpaul</pre> 13990297Sdesproducing output like: 14013394Swpaul<pre> 14113394Swpaul ... 14213394Swpaul java.util.ArrayList.add 14313394Swpaul index - index at which the specified element is to be inserted. 14413394Swpaul element - element to be inserted. 14513394Swpaul java.util.ArrayList.remove 14613394Swpaul index - the index of the element to removed. 14713394Swpaul ... 14813394Swpaul 14913799Swpaul</pre> 15013394Swpaul@see com.sun.javadoc.Doclet 15113394Swpaul@see com.sun.javadoc.RootDoc 15290297Sdes*/ 15313394Swpaulpackage com.sun.javadoc; 15413394Swpaul