Thu, 10 Jun 2010 16:08:01 -0700
6944312: Potential rebranding issues in openjdk/langtools repository sources
Reviewed-by: darcy
duke@1 | 1 | <html> |
duke@1 | 2 | <head> |
duke@1 | 3 | <TITLE>Doclet API Package</TITLE> |
duke@1 | 4 | <!-- |
duke@1 | 5 | |
ohair@554 | 6 | Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved. |
duke@1 | 7 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
duke@1 | 8 | |
duke@1 | 9 | This code is free software; you can redistribute it and/or modify it |
duke@1 | 10 | under the terms of the GNU General Public License version 2 only, as |
ohair@554 | 11 | published by the Free Software Foundation. Oracle designates this |
duke@1 | 12 | particular file as subject to the "Classpath" exception as provided |
ohair@554 | 13 | by Oracle in the LICENSE file that accompanied this code. |
duke@1 | 14 | |
duke@1 | 15 | This code is distributed in the hope that it will be useful, but WITHOUT |
duke@1 | 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
duke@1 | 17 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
duke@1 | 18 | version 2 for more details (a copy is included in the LICENSE file that |
duke@1 | 19 | accompanied this code). |
duke@1 | 20 | |
duke@1 | 21 | You should have received a copy of the GNU General Public License version |
duke@1 | 22 | 2 along with this work; if not, write to the Free Software Foundation, |
duke@1 | 23 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
duke@1 | 24 | |
ohair@557 | 25 | Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
ohair@557 | 26 | or visit www.oracle.com if you need additional information or have any |
ohair@557 | 27 | questions. |
duke@1 | 28 | --> |
duke@1 | 29 | </head> |
duke@1 | 30 | <body bgcolor="white"> |
duke@1 | 31 | |
duke@1 | 32 | The Doclet API (also called the Javadoc API) provides a mechanism |
duke@1 | 33 | for clients to inspect the source-level structure of programs and |
duke@1 | 34 | libraries, including javadoc comments embedded in the source. |
duke@1 | 35 | This is useful for documentation, program checking, automatic |
duke@1 | 36 | code generation and many other tools. |
duke@1 | 37 | <p> |
duke@1 | 38 | |
duke@1 | 39 | Doclets are invoked by javadoc and use this API to write out |
duke@1 | 40 | program information to files. For example, the standard doclet is called |
duke@1 | 41 | by default and writes out documentation to HTML files. |
duke@1 | 42 | <p> |
duke@1 | 43 | |
duke@1 | 44 | The invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class |
duke@1 | 45 | -- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: |
duke@1 | 46 | <pre> |
duke@1 | 47 | public static boolean <b>start</b>(RootDoc root) |
duke@1 | 48 | </pre> |
duke@1 | 49 | The {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure |
duke@1 | 50 | information. From this root all other program structure |
duke@1 | 51 | information can be extracted. |
duke@1 | 52 | <p> |
duke@1 | 53 | |
duke@1 | 54 | <a name="terminology"></a> |
duke@1 | 55 | <h3>Terminology</h3> |
duke@1 | 56 | |
duke@1 | 57 | <a name="included"></a> |
duke@1 | 58 | When calling javadoc, you pass in package names and source file names -- |
duke@1 | 59 | these are called the <em>specified</em> packages and classes. |
duke@1 | 60 | You also pass in Javadoc options; the <em>access control</em> Javadoc options |
duke@1 | 61 | (<code>-public</code>, <code>-protected</code>, <code>-package</code>, |
duke@1 | 62 | and <code>-private</code>) filter program elements, producing a |
duke@1 | 63 | result set, called the <em>included</em> set, or "documented" set. |
duke@1 | 64 | (The unfiltered set is also available through |
duke@1 | 65 | {@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) |
duke@1 | 66 | <p> |
duke@1 | 67 | |
duke@1 | 68 | <a name="class"></a> |
duke@1 | 69 | Throughout this API, the term <em>class</em> is normally a |
duke@1 | 70 | shorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, |
duke@1 | 71 | {@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and |
duke@1 | 72 | {@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. |
duke@1 | 73 | In only a couple of other places, it means "class, as opposed to interface", |
duke@1 | 74 | as in: {@link com.sun.javadoc.Doc#isClass()}. |
duke@1 | 75 | In the second sense, this API calls out four kinds of classes: |
duke@1 | 76 | {@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, |
duke@1 | 77 | {@linkplain com.sun.javadoc.Doc#isEnum() enums}, |
duke@1 | 78 | {@linkplain com.sun.javadoc.Doc#isError() errors} and |
duke@1 | 79 | {@linkplain com.sun.javadoc.Doc#isException() exceptions}. |
duke@1 | 80 | Throughout the API, the detailed description of each program element |
duke@1 | 81 | describes explicitly which meaning is being used. |
duke@1 | 82 | <p> |
duke@1 | 83 | |
duke@1 | 84 | <a name="qualified"></a> |
duke@1 | 85 | A <em>qualified</em> class or interface name is one that has its package |
duke@1 | 86 | name prepended to it, such as <code>java.lang.String</code>. A non-qualified |
duke@1 | 87 | name has no package name, such as <code>String</code>. |
duke@1 | 88 | <p> |
duke@1 | 89 | |
duke@1 | 90 | <a name="example"></a> |
duke@1 | 91 | <h3>Example</h3> |
duke@1 | 92 | |
duke@1 | 93 | The following is an example doclet that |
duke@1 | 94 | displays information in the <code>@param</code> tags of the processed |
duke@1 | 95 | classes: |
duke@1 | 96 | <pre> |
duke@1 | 97 | import com.sun.javadoc.*; |
duke@1 | 98 | |
duke@1 | 99 | public class ListParams extends <font color=red title="Doclet API">Doclet</font> { |
duke@1 | 100 | |
duke@1 | 101 | public static boolean start(<font color=red title="Doclet API">RootDoc</font> root) { |
duke@1 | 102 | <font color=red title="Doclet API">ClassDoc</font>[] classes = root.<font color=red title="Doclet API">classes</font>(); |
duke@1 | 103 | for (int i = 0; i < classes.length; ++i) { |
duke@1 | 104 | <font color=red title="Doclet API">ClassDoc</font> cd = classes[i]; |
duke@1 | 105 | printMembers(cd.<font color=red title="Doclet API">constructors</font>()); |
duke@1 | 106 | printMembers(cd.<font color=red title="Doclet API">methods</font>()); |
duke@1 | 107 | } |
duke@1 | 108 | return true; |
duke@1 | 109 | } |
duke@1 | 110 | |
duke@1 | 111 | static void printMembers(<font color=red title="Doclet API">ExecutableMemberDoc</font>[] mems) { |
duke@1 | 112 | for (int i = 0; i < mems.length; ++i) { |
duke@1 | 113 | <font color=red title="Doclet API">ParamTag</font>[] params = mems[i].<font color=red title="Doclet API">paramTags</font>(); |
duke@1 | 114 | System.out.println(mems[i].<font color=red title="Doclet API">qualifiedName</font>()); |
duke@1 | 115 | for (int j = 0; j < params.length; ++j) { |
duke@1 | 116 | System.out.println(" " + params[j].<font color=red title="Doclet API">parameterName</font>() |
duke@1 | 117 | + " - " + params[j].<font color=red title="Doclet API">parameterComment</font>()); |
duke@1 | 118 | } |
duke@1 | 119 | } |
duke@1 | 120 | } |
duke@1 | 121 | } |
duke@1 | 122 | </pre> |
duke@1 | 123 | Interfaces and methods from the Javadoc API are marked in |
duke@1 | 124 | <font color=red title="Doclet API">red</font>. |
duke@1 | 125 | {@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies |
duke@1 | 126 | the invocation interface for doclets, |
duke@1 | 127 | {@link com.sun.javadoc.Doclet Doclet} holds class or interface information, |
duke@1 | 128 | {@link com.sun.javadoc.ExecutableMemberDoc} is a |
duke@1 | 129 | superinterface of {@link com.sun.javadoc.MethodDoc} and |
duke@1 | 130 | {@link com.sun.javadoc.ConstructorDoc}, |
duke@1 | 131 | and {@link com.sun.javadoc.ParamTag} holds information |
duke@1 | 132 | from "<code>@param</code>" tags. |
duke@1 | 133 | <p> |
duke@1 | 134 | This doclet when invoked with a command line like: |
duke@1 | 135 | <pre> |
duke@1 | 136 | javadoc -doclet ListParams -sourcepath <source-location> java.util |
duke@1 | 137 | </pre> |
duke@1 | 138 | producing output like: |
duke@1 | 139 | <pre> |
duke@1 | 140 | ... |
duke@1 | 141 | java.util.ArrayList.add |
duke@1 | 142 | index - index at which the specified element is to be inserted. |
duke@1 | 143 | element - element to be inserted. |
duke@1 | 144 | java.util.ArrayList.remove |
duke@1 | 145 | index - the index of the element to removed. |
duke@1 | 146 | ... |
duke@1 | 147 | |
duke@1 | 148 | </pre> |
duke@1 | 149 | @see com.sun.javadoc.Doclet |
duke@1 | 150 | @see com.sun.javadoc.RootDoc |
duke@1 | 151 | </BODY> |
duke@1 | 152 | </HTML> |