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