Tue, 30 Oct 2012 10:15:19 -0700
8001929: fix doclint errors in langtools doc comments
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 package com.sun.tools.doclets.internal.toolkit.util;
28 import com.sun.javadoc.ClassDoc;
29 import com.sun.javadoc.PackageDoc;
30 import java.io.File;
32 /**
33 * Abstraction for immutable relative paths.
34 * Paths always use '/' as a separator, and never begin or end with '/'.
35 *
36 * <p><b>This is NOT part of any supported API.
37 * If you write code that depends on this, you do so at your own risk.
38 * This code and its internal interfaces are subject to change or
39 * deletion without notice.</b>
40 */
41 public class DocPath {
42 private final String path;
44 /** The empty path. */
45 public static final DocPath empty = new DocPath("");
47 /** The empty path. */
48 public static final DocPath parent = new DocPath("..");
50 /**
51 * Create a path from a string.
52 */
53 public static DocPath create(String p) {
54 return (p == null) || p.isEmpty() ? empty : new DocPath(p);
55 }
57 /**
58 * Return the path for a class.
59 * For example, if the class is java.lang.Object,
60 * the path is java/lang/Object.html.
61 */
62 public static DocPath forClass(ClassDoc cd) {
63 return (cd == null) ? empty :
64 forPackage(cd.containingPackage()).resolve(forName(cd));
65 }
67 /**
68 * Return the path for the simple name of the class.
69 * For example, if the class is java.lang.Object,
70 * the path is Object.html.
71 */
72 public static DocPath forName(ClassDoc cd) {
73 return (cd == null) ? empty : new DocPath(cd.name() + ".html");
74 }
76 /**
77 * Return the path for the package of a class.
78 * For example, if the class is java.lang.Object,
79 * the path is java/lang.
80 */
81 public static DocPath forPackage(ClassDoc cd) {
82 return (cd == null) ? empty : forPackage(cd.containingPackage());
83 }
85 /**
86 * Return the path for a package.
87 * For example, if the package is java.lang,
88 * the path is java/lang.
89 */
90 public static DocPath forPackage(PackageDoc pd) {
91 return (pd == null) ? empty : DocPath.create(pd.name().replace('.', '/'));
92 }
94 /**
95 * Return the inverse path for a package.
96 * For example, if the package is java.lang,
97 * the inverse path is ../...
98 */
99 public static DocPath forRoot(PackageDoc pd) {
100 String name = (pd == null) ? "" : pd.name();
101 if (name.isEmpty())
102 return empty;
103 return new DocPath(name.replace('.', '/').replaceAll("[^/]+", ".."));
104 }
106 /**
107 * Return the relative path from one package to another.
108 */
109 public static DocPath relativePath(PackageDoc from, PackageDoc to) {
110 return forRoot(from).resolve(forPackage(to));
111 }
113 protected DocPath(String p) {
114 path = (p.endsWith("/") ? p.substring(0, p.length() - 1) : p);
115 }
117 /** {@inheritDoc} */
118 @Override
119 public boolean equals(Object other) {
120 return (other instanceof DocPath) && path.equals(((DocPath)other).path);
121 }
123 /** {@inheritDoc} */
124 @Override
125 public int hashCode() {
126 return path.hashCode();
127 }
129 public DocPath basename() {
130 int sep = path.lastIndexOf("/");
131 return (sep == -1) ? this : new DocPath(path.substring(sep + 1));
132 }
134 public DocPath parent() {
135 int sep = path.lastIndexOf("/");
136 return (sep == -1) ? empty : new DocPath(path.substring(0, sep));
137 }
139 /**
140 * Return the path formed by appending the specified string to the current path.
141 */
142 public DocPath resolve(String p) {
143 if (p == null || p.isEmpty())
144 return this;
145 if (path.isEmpty())
146 return new DocPath(p);
147 return new DocPath(path + "/" + p);
148 }
150 /**
151 * Return the path by appending the specified path to the current path.
152 */
153 public DocPath resolve(DocPath p) {
154 if (p == null || p.isEmpty())
155 return this;
156 if (path.isEmpty())
157 return p;
158 return new DocPath(path + "/" + p.getPath());
159 }
161 /**
162 * Get the file created by evaluating the path against a specified directory.
163 */
164 // Temporary: this signature should not use String for dir.
165 // Eventually, this should involve javax.tools.Location.
166 public File resolveAgainst(String dir) {
167 return dir.isEmpty() ? new File(path) : new File(dir, path);
168 }
170 /**
171 * Return the inverse path for this path.
172 * For example, if the path is a/b/c, the inverse path is ../../..
173 */
174 public DocPath invert() {
175 return new DocPath(path.replaceAll("[^/]+", ".."));
176 }
178 /**
179 * Return true if this path is empty.
180 */
181 public boolean isEmpty() {
182 return path.isEmpty();
183 }
185 public DocLink fragment(String fragment) {
186 return new DocLink(path, null, fragment);
187 }
189 public DocLink query(String query) {
190 return new DocLink(path, query, null);
191 }
193 /**
194 * Return this path as a string.
195 */
196 // This is provided instead of using toString() to help catch
197 // unintended use of toString() in string concatenation sequences.
198 public String getPath() {
199 return path;
200 }
201 }