package-info.java revision 2571:10fc81ac75b4
1221828Sgrehan/* 2221828Sgrehan * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. 3221828Sgrehan * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4221828Sgrehan * 5221828Sgrehan * This code is free software; you can redistribute it and/or modify it 6221828Sgrehan * under the terms of the GNU General Public License version 2 only, as 7221828Sgrehan * published by the Free Software Foundation. Oracle designates this 8221828Sgrehan * particular file as subject to the "Classpath" exception as provided 9221828Sgrehan * by Oracle in the LICENSE file that accompanied this code. 10221828Sgrehan * 11221828Sgrehan * This code is distributed in the hope that it will be useful, but WITHOUT 12221828Sgrehan * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13221828Sgrehan * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14221828Sgrehan * version 2 for more details (a copy is included in the LICENSE file that 15221828Sgrehan * accompanied this code). 16221828Sgrehan * 17221828Sgrehan * You should have received a copy of the GNU General Public License version 18221828Sgrehan * 2 along with this work; if not, write to the Free Software Foundation, 19221828Sgrehan * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20221828Sgrehan * 21221828Sgrehan * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22221828Sgrehan * or visit www.oracle.com if you need additional information or have any 23221828Sgrehan * questions. 24221828Sgrehan */ 25221828Sgrehan 26221828Sgrehan/** 27221828SgrehanThe Doclet API (also called the Javadoc API) provides a mechanism 28221828Sgrehanfor clients to inspect the source-level structure of programs and 29221828Sgrehanlibraries, including javadoc comments embedded in the source. 30221828SgrehanThis is useful for documentation, program checking, automatic 31221828Sgrehancode generation and many other tools. 32221828Sgrehan<p> 33221828Sgrehan 34221828SgrehanDoclets are invoked by javadoc and use this API to write out 35221828Sgrehanprogram information to files. For example, the standard doclet is called 36221828Sgrehanby default and writes out documentation to HTML files. 37221828Sgrehan<p> 38221828Sgrehan 39221828SgrehanThe invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class 40221828Sgrehan-- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: 41221828Sgrehan<pre> 42221828Sgrehan public static boolean <b>start</b>(RootDoc root) 43240922Sneel</pre> 44240922SneelThe {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure 45221828Sgrehaninformation. From this root all other program structure 46221828Sgrehaninformation can be extracted. 47221828Sgrehan<p> 48240894Sneel 49221828Sgrehan<a name="terminology"></a> 50241147Sneel<h3>Terminology</h3> 51241147Sneel 52241147Sneel<a name="included"></a> 53241147SneelWhen calling javadoc, you pass in package names and source file names -- 54241147Sneelthese are called the <em>specified</em> packages and classes. 55221828SgrehanYou also pass in Javadoc options; the <em>access control</em> Javadoc options 56221828Sgrehan({@code -public}, {@code -protected}, {@code -package}, 57221828Sgrehanand {@code -private}) filter program elements, producing a 58221828Sgrehanresult set, called the <em>included</em> set, or "documented" set. 59221828Sgrehan(The unfiltered set is also available through 60221828Sgrehan{@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) 61221828Sgrehan<p> 62221828Sgrehan 63221828Sgrehan<a name="class"></a> 64221828SgrehanThroughout this API, the term <em>class</em> is normally a 65221828Sgrehanshorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, 66221828Sgrehan{@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and 67221828Sgrehan{@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. 68221828SgrehanIn only a couple of other places, it means "class, as opposed to interface", 69221828Sgrehanas in: {@link com.sun.javadoc.Doc#isClass()}. 70221828SgrehanIn the second sense, this API calls out four kinds of classes: 71221828Sgrehan{@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, 72221828Sgrehan{@linkplain com.sun.javadoc.Doc#isEnum() enums}, 73221828Sgrehan{@linkplain com.sun.javadoc.Doc#isError() errors} and 74221828Sgrehan{@linkplain com.sun.javadoc.Doc#isException() exceptions}. 75221828SgrehanThroughout the API, the detailed description of each program element 76241147Sneeldescribes explicitly which meaning is being used. 77241147Sneel<p> 78221828Sgrehan 79221828Sgrehan<a name="qualified"></a> 80221828SgrehanA <em>qualified</em> class or interface name is one that has its package 81221828Sgrehanname prepended to it, such as {@code java.lang.String}. A non-qualified 82221828Sgrehanname has no package name, such as {@code String}. 83221828Sgrehan<p> 84221828Sgrehan 85221828Sgrehan<a name="example"></a> 86221828Sgrehan<h3>Example</h3> 87221828Sgrehan 88221828SgrehanThe following is an example doclet that 89221828Sgrehandisplays information in the {@code @param} tags of the processed 90221828Sgrehanclasses: 91221828Sgrehan<pre> 92221828Sgrehanimport com.sun.javadoc.*; 93241041Sneel 94221828Sgrehanpublic class ListParams extends <span style="color:red" >Doclet</span> { 95221828Sgrehan 96221828Sgrehan public static boolean start(<span style="color:red" >RootDoc</span> root) { 97221828Sgrehan <span style="color:red" >ClassDoc</span>[] classes = root.<span style="color:red" >classes</span>(); 98221828Sgrehan for (int i = 0; i < classes.length; ++i) { 99221828Sgrehan <span style="color:red" >ClassDoc</span> cd = classes[i]; 100221828Sgrehan printMembers(cd.<span style="color:red" >constructors</span>()); 101221828Sgrehan printMembers(cd.<span style="color:red" >methods</span>()); 102221828Sgrehan } 103221828Sgrehan return true; 104221828Sgrehan } 105221828Sgrehan 106221828Sgrehan static void printMembers(<span style="color:red" >ExecutableMemberDoc</span>[] mems) { 107221828Sgrehan for (int i = 0; i < mems.length; ++i) { 108221828Sgrehan <span style="color:red" >ParamTag</span>[] params = mems[i].<span style="color:red" >paramTags</span>(); 109221828Sgrehan System.out.println(mems[i].<span style="color:red" >qualifiedName</span>()); 110221828Sgrehan for (int j = 0; j < params.length; ++j) { 111241982Sneel System.out.println(" " + params[j].<span style="color:red" >parameterName</span>() 112241982Sneel + " - " + params[j].<span style="color:red" >parameterComment</span>()); 113221828Sgrehan } 114221828Sgrehan } 115221828Sgrehan } 116221828Sgrehan} 117240922Sneel</pre> 118240922SneelInterfaces and methods from the Javadoc API are marked in 119221828Sgrehan<span style="color:red" >red</span>. 120223621Sgrehan{@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies 121240894Sneelthe invocation interface for doclets, 122221828Sgrehan{@link com.sun.javadoc.Doclet Doclet} holds class or interface information, 123221828Sgrehan{@link com.sun.javadoc.ExecutableMemberDoc} is a 124221828Sgrehansuperinterface of {@link com.sun.javadoc.MethodDoc} and 125221828Sgrehan{@link com.sun.javadoc.ConstructorDoc}, 126221828Sgrehanand {@link com.sun.javadoc.ParamTag} holds information 127221828Sgrehanfrom "{@code @param}" tags. 128221828Sgrehan<p> 129221828SgrehanThis doclet when invoked with a command line like: 130221828Sgrehan<pre> 131221828Sgrehan javadoc -doclet ListParams -sourcepath <source-location> java.util 132221828Sgrehan</pre> 133241489Sneelproducing output like: 134241489Sneel<pre> 135241489Sneel ... 136241489Sneel java.util.ArrayList.add 137241489Sneel index - index at which the specified element is to be inserted. 138221828Sgrehan element - element to be inserted. 139241489Sneel java.util.ArrayList.remove 140241489Sneel index - the index of the element to removed. 141221828Sgrehan ... 142221828Sgrehan 143241489Sneel</pre> 144221828Sgrehan@see com.sun.javadoc.Doclet 145241489Sneel@see com.sun.javadoc.RootDoc 146221828Sgrehan*/ 147221828Sgrehan@jdk.Exported 148241489Sneelpackage com.sun.javadoc; 149241489Sneel