| 1 |
/* |
| 2 |
* Copyright (c) 2016-present, RxJava Contributors. |
| 3 |
* |
| 4 |
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in |
| 5 |
* compliance with the License. You may obtain a copy of the License at |
| 6 |
* |
| 7 |
* http://www.apache.org/licenses/LICENSE-2.0 |
| 8 |
* |
| 9 |
* Unless required by applicable law or agreed to in writing, software distributed under the License is |
| 10 |
* distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See |
| 11 |
* the License for the specific language governing permissions and limitations under the License. |
| 12 |
*/ |
| 13 |
|
| 14 |
package io.reactivex.rxjava3.validators; |
| 15 |
|
| 16 |
import java.io.File; |
| 17 |
import java.nio.file.Files; |
| 18 |
import java.util.*; |
| 19 |
|
| 20 |
import org.junit.Test; |
| 21 |
|
| 22 |
import io.reactivex.rxjava3.testsupport.TestHelper; |
| 23 |
|
| 24 |
/** |
| 25 |
* Scan the Javadocs of a source and check if mentions of other classes, |
| 26 |
* interfaces and enums are using at-link and at-code wrapping for style. |
| 27 |
* <p> |
| 28 |
* The check ignores html tag content on a line, @see and @throws entries |
| 29 |
* and <code></code> lines. |
| 30 |
*/ |
| 31 |
public class JavadocCodesAndLinks { |
| 32 |
|
| 33 |
@Test |
| 34 |
public void checkFlowable() throws Exception { |
| 35 |
checkSource("Flowable", "io.reactivex.rxjava3.core"); |
| 36 |
} |
| 37 |
|
| 38 |
@Test |
| 39 |
public void checkCompletable() throws Exception { |
| 40 |
checkSource("Completable", "io.reactivex.rxjava3.core"); |
| 41 |
} |
| 42 |
|
| 43 |
@Test |
| 44 |
public void checkSingle() throws Exception { |
| 45 |
checkSource("Single", "io.reactivex.rxjava3.core"); |
| 46 |
} |
| 47 |
|
| 48 |
@Test |
| 49 |
public void checkMaybe() throws Exception { |
| 50 |
checkSource("Maybe", "io.reactivex.rxjava3.core"); |
| 51 |
} |
| 52 |
|
| 53 |
@Test |
| 54 |
public void checkObservable() throws Exception { |
| 55 |
checkSource("Observable", "io.reactivex.rxjava3.core"); |
| 56 |
} |
| 57 |
|
| 58 |
@Test |
| 59 |
public void checkParallelFlowable() throws Exception { |
| 60 |
checkSource("ParallelFlowable", "io.reactivex.rxjava3.parallel"); |
| 61 |
} |
| 62 |
|
| 63 |
@Test |
| 64 |
public void checkCompositeDisposable() throws Exception { |
| 65 |
checkSource("CompositeDisposable", "io.reactivex.rxjava3.disposables"); |
| 66 |
} |
| 67 |
|
| 68 |
@Test |
| 69 |
public void checkConnectableFlowable() throws Exception { |
| 70 |
checkSource("ConnectableFlowable", "io.reactivex.rxjava3.flowables"); |
| 71 |
} |
| 72 |
|
| 73 |
@Test |
| 74 |
public void checkConnectableObservable() throws Exception { |
| 75 |
checkSource("ConnectableObservable", "io.reactivex.rxjava3.observables"); |
| 76 |
} |
| 77 |
|
| 78 |
@Test |
| 79 |
public void checkSchedulers() throws Exception { |
| 80 |
checkSource("Schedulers", "io.reactivex.rxjava3.schedulers"); |
| 81 |
} |
| 82 |
|
| 83 |
static void checkSource(String baseClassName, String packageName) throws Exception { |
| 84 |
File f = TestHelper.findSource(baseClassName, packageName); |
| 85 |
if (f == null) { |
| 86 |
return; |
| 87 |
} |
| 88 |
|
| 89 |
StringBuilder errors = new StringBuilder(2048); |
| 90 |
int errorCount = 0; |
| 91 |
|
| 92 |
List<String> lines = Files.readAllLines(f.toPath()); |
| 93 |
|
| 94 |
List<String> docs = new ArrayList<>(); |
| 95 |
|
| 96 |
// i = 1 skip the header javadoc |
| 97 |
for (int i = 1; i < lines.size(); i++) { |
| 98 |
|
| 99 |
if (lines.get(i).trim().equals("/**")) { |
| 100 |
docs.clear(); |
| 101 |
|
| 102 |
boolean skipCode = false; |
| 103 |
for (int j = i + 1; j < lines.size(); j++) { |
| 104 |
String line = lines.get(j).trim(); |
| 105 |
if (line.contains("<code>")) { |
| 106 |
skipCode = true; |
| 107 |
} |
| 108 |
if (line.equals("*/")) { |
| 109 |
break; |
| 110 |
} |
| 111 |
if (!skipCode) { |
| 112 |
// strip <a> </a> |
| 113 |
line = stripTags(line); |
| 114 |
if (line.startsWith("@see")) { |
| 115 |
docs.add(""); |
| 116 |
} |
| 117 |
else if (line.startsWith("@throws") || line.startsWith("@param")) { |
| 118 |
int space = line.indexOf(' '); |
| 119 |
if (space < 0) { |
| 120 |
docs.add(""); |
| 121 |
} else { |
| 122 |
space = line.indexOf(" ", space + 1); |
| 123 |
if (space < 0) { |
| 124 |
docs.add(""); |
| 125 |
} else { |
| 126 |
docs.add(line.substring(space + 1)); |
| 127 |
} |
| 128 |
} |
| 129 |
} else { |
| 130 |
docs.add(line); |
| 131 |
} |
| 132 |
} else { |
| 133 |
docs.add(""); |
| 134 |
} |
| 135 |
if (line.contains("</code>")) { |
| 136 |
skipCode = false; |
| 137 |
} |
| 138 |
} |
| 139 |
|
| 140 |
for (String name : NAMES) { |
| 141 |
boolean isHostType = name.equals(baseClassName); |
| 142 |
boolean isAlwaysCode = ALWAYS_CODE.contains(name); |
| 143 |
String asLink = "{@link " + name + "}"; |
| 144 |
String asCode = "{@code " + name + "}"; |
| 145 |
boolean seenBefore = false; |
| 146 |
|
| 147 |
for (int j = 0; j < docs.size(); j++) { |
| 148 |
String line = docs.get(j); |
| 149 |
|
| 150 |
int idxLink = line.indexOf(asLink); |
| 151 |
if (idxLink >= 0 && !isHostType && !isAlwaysCode) { |
| 152 |
int k = idxLink + asLink.length(); |
| 153 |
for (;;) { |
| 154 |
int jdxLink = line.indexOf(asLink, k); |
| 155 |
if (jdxLink < 0) { |
| 156 |
break; |
| 157 |
} |
| 158 |
if (jdxLink >= 0) { |
| 159 |
errorCount++; |
| 160 |
errors.append("The subsequent mention should be code: ") |
| 161 |
.append("{@code ").append(name) |
| 162 |
.append("}\r\n at ") |
| 163 |
.append(packageName) |
| 164 |
.append(".") |
| 165 |
.append(baseClassName) |
| 166 |
.append(".method(") |
| 167 |
.append(baseClassName) |
| 168 |
.append(".java:") |
| 169 |
.append(i + 2 + j) |
| 170 |
.append(")\r\n"); |
| 171 |
} |
| 172 |
k = jdxLink + asLink.length(); |
| 173 |
} |
| 174 |
} |
| 175 |
if (seenBefore) { |
| 176 |
if (idxLink >= 0 && !isHostType && !isAlwaysCode) { |
| 177 |
errorCount++; |
| 178 |
errors.append("The subsequent mention should be code: ") |
| 179 |
.append("{@code ").append(name) |
| 180 |
.append("}\r\n at ") |
| 181 |
.append(packageName) |
| 182 |
.append(".") |
| 183 |
.append(baseClassName) |
| 184 |
.append(".method(") |
| 185 |
.append(baseClassName) |
| 186 |
.append(".java:") |
| 187 |
.append(i + 2 + j) |
| 188 |
.append(")\r\n"); |
| 189 |
} |
| 190 |
} else { |
| 191 |
int idxCode = line.indexOf(asCode); |
| 192 |
|
| 193 |
if (isHostType) { |
| 194 |
if (idxLink >= 0) { |
| 195 |
errorCount++; |
| 196 |
errors.append("The host type mention should be code: ") |
| 197 |
.append("{@code ").append(name) |
| 198 |
.append("}\r\n at ") |
| 199 |
.append(packageName) |
| 200 |
.append(".") |
| 201 |
.append(baseClassName) |
| 202 |
.append(".method(") |
| 203 |
.append(baseClassName) |
| 204 |
.append(".java:") |
| 205 |
.append(i + 2 + j) |
| 206 |
.append(")\r\n"); |
| 207 |
} |
| 208 |
} else { |
| 209 |
if ((idxLink < 0 && idxCode >= 0 && !isAlwaysCode) |
| 210 |
|| (idxLink >= 0 && idxCode >= 0 && idxCode < idxLink)) { |
| 211 |
errorCount++; |
| 212 |
if (isAlwaysCode) { |
| 213 |
errors.append("The first mention should be code: ") |
| 214 |
.append("{@code ") |
| 215 |
; |
| 216 |
} else { |
| 217 |
errors.append("The first mention should be link: ") |
| 218 |
.append("{@link ") |
| 219 |
; |
| 220 |
} |
| 221 |
errors |
| 222 |
.append(name) |
| 223 |
.append("}\r\n at ") |
| 224 |
.append(packageName) |
| 225 |
.append(".") |
| 226 |
.append(baseClassName) |
| 227 |
.append(".method(") |
| 228 |
.append(baseClassName) |
| 229 |
.append(".java:") |
| 230 |
.append(i + 2 + j) |
| 231 |
.append(")\r\n"); |
| 232 |
} |
| 233 |
} |
| 234 |
|
| 235 |
seenBefore = idxLink >= 0 || idxCode >= 0; |
| 236 |
} |
| 237 |
|
| 238 |
// strip out all existing {@code } and {@link } instances |
| 239 |
String noCurly = removeCurlies(line); |
| 240 |
|
| 241 |
int k = 0; |
| 242 |
|
| 243 |
for (;;) { |
| 244 |
int idx = noCurly.indexOf(name, k); |
| 245 |
if (idx < 0) { |
| 246 |
break; |
| 247 |
} |
| 248 |
k = idx + name.length(); |
| 249 |
|
| 250 |
if (isHostType) { |
| 251 |
errorCount++; |
| 252 |
errors.append("The host type mention should be code: ") |
| 253 |
.append("{@code ").append(name) |
| 254 |
.append("}\r\n at ") |
| 255 |
.append(packageName) |
| 256 |
.append(".") |
| 257 |
.append(baseClassName) |
| 258 |
.append(".method(") |
| 259 |
.append(baseClassName) |
| 260 |
.append(".java:") |
| 261 |
.append(i + 2 + j) |
| 262 |
.append(")\r\n"); |
| 263 |
} |
| 264 |
else if (!seenBefore) { |
| 265 |
errorCount++; |
| 266 |
if (isAlwaysCode) { |
| 267 |
errors.append("The first mention should be code: ") |
| 268 |
.append("{@code "); |
| 269 |
} else { |
| 270 |
errors.append("The first mention should be link: ") |
| 271 |
.append("{@link "); |
| 272 |
} |
| 273 |
errors |
| 274 |
.append(name) |
| 275 |
.append("}\r\n at ") |
| 276 |
.append(packageName) |
| 277 |
.append(".") |
| 278 |
.append(baseClassName) |
| 279 |
.append(".method(") |
| 280 |
.append(baseClassName) |
| 281 |
.append(".java:") |
| 282 |
.append(i + 2 + j) |
| 283 |
.append(")\r\n"); |
| 284 |
} else { |
| 285 |
errorCount++; |
| 286 |
errors.append("The subsequent mention should be code: ") |
| 287 |
.append("{@code ").append(name) |
| 288 |
.append("}\r\n at ") |
| 289 |
.append(packageName) |
| 290 |
.append(".") |
| 291 |
.append(baseClassName) |
| 292 |
.append(".method(") |
| 293 |
.append(baseClassName) |
| 294 |
.append(".java:") |
| 295 |
.append(i + 2 + j) |
| 296 |
.append(")\r\n"); |
| 297 |
} |
| 298 |
|
| 299 |
seenBefore = true; |
| 300 |
} |
| 301 |
} |
| 302 |
} |
| 303 |
|
| 304 |
i += docs.size(); |
| 305 |
|
| 306 |
if (errorCount >= ERROR_LIMIT) { |
| 307 |
break; |
| 308 |
} |
| 309 |
} |
| 310 |
} |
| 311 |
|
| 312 |
if (errorCount != 0) { |
| 313 |
errors.insert(0, "Found " + (errorCount > ERROR_LIMIT ? ERROR_LIMIT + "+" : errorCount + "") + " cases\r\n"); |
| 314 |
throw new AssertionError(errors.toString()); |
| 315 |
} |
| 316 |
} |
| 317 |
|
| 318 |
static String removeCurlies(String input) { |
| 319 |
StringBuilder result = new StringBuilder(input.length()); |
| 320 |
|
| 321 |
boolean skip = false; |
| 322 |
for (int i = 0; i < input.length(); i++) { |
| 323 |
char c = input.charAt(i); |
| 324 |
if (c == '{') { |
| 325 |
skip = true; |
| 326 |
} |
| 327 |
if (!skip) { |
| 328 |
result.append(c); |
| 329 |
} |
| 330 |
if (c == '}') { |
| 331 |
skip = false; |
| 332 |
} |
| 333 |
} |
| 334 |
|
| 335 |
return result.toString(); |
| 336 |
} |
| 337 |
|
| 338 |
static String stripTags(String input) { |
| 339 |
StringBuilder result = new StringBuilder(input.length()); |
| 340 |
result.append(input, input.length() > 1 ? 2 : 1, input.length()); |
| 341 |
|
| 342 |
clearTag(result, "<a ", "</a>"); |
| 343 |
clearTag(result, "<b>", "</b>"); |
| 344 |
clearTag(result, "<strong>", "</strong>"); |
| 345 |
clearTag(result, "<em>", "</em>"); |
| 346 |
clearTag(result, "<img ", ">"); |
| 347 |
|
| 348 |
return result.toString(); |
| 349 |
} |
| 350 |
|
| 351 |
static void clearTag(StringBuilder builder, String startTag, String endTag) { |
| 352 |
int k = 0; |
| 353 |
for (;;) { |
| 354 |
int j = builder.indexOf(startTag, k); |
| 355 |
if (j < 0) { |
| 356 |
break; |
| 357 |
} |
| 358 |
|
| 359 |
int e = builder.indexOf(endTag, j); |
| 360 |
if (e < 0) { |
| 361 |
e = builder.length(); |
| 362 |
} |
| 363 |
|
| 364 |
blankRange(builder, j, e); |
| 365 |
|
| 366 |
k = e + endTag.length(); |
| 367 |
} |
| 368 |
} |
| 369 |
|
| 370 |
static void blankRange(StringBuilder builder, int start, int end) { |
| 371 |
for (int i = start; i < end; i++) { |
| 372 |
int c = builder.charAt(i); |
| 373 |
if (c != '\r' && c != '\n') { |
| 374 |
builder.setCharAt(i, ' '); |
| 375 |
} |
| 376 |
} |
| 377 |
} |
| 378 |
|
| 379 |
static final List<String> NAMES = Arrays.asList( |
| 380 |
"Flowable", "Observable", "Maybe", "Single", "Completable", "ParallelFlowable", |
| 381 |
|
| 382 |
"Publisher", "ObservableSource", "MaybeSource", "SingleSource", "CompletableSource", |
| 383 |
|
| 384 |
"FlowableSubscriber", "Subscriber", "Observer", "MaybeObserver", "SingleObserver", "CompletableObserver", |
| 385 |
|
| 386 |
"FlowableOperator", "ObservableOperator", "MaybeOperator", "SingleOperator", "CompletableOperator", |
| 387 |
|
| 388 |
"FlowableOnSubscribe", "ObservableOnSubscribe", "MaybeOnSubscribe", "SingleOnSubscribe", "CompletableOnSubscribe", |
| 389 |
|
| 390 |
"FlowableTransformer", "ObservableTransformer", "MaybeTransformer", "SingleTransformer", "CompletableTransformer", "ParallelTransformer", |
| 391 |
|
| 392 |
"FlowableConverter", "ObservableConverter", "MaybeConverter", "SingleConverter", "CompletableConverter", |
| 393 |
|
| 394 |
"FlowableEmitter", "ObservableEmitter", "MaybeEmitter", "SingleEmitter", "CompletableEmitter", |
| 395 |
|
| 396 |
"Iterable", "Stream", |
| 397 |
|
| 398 |
"Function", "BiFunction", "Function3", "Function4", "Function5", "Function6", "Function7", "Function8", "Function9", |
| 399 |
|
| 400 |
"Action", "Runnable", "Disposable", "Subscription", "Consumer", "BiConsumer", "Future", |
| 401 |
|
| 402 |
"Supplier", "Callable", "TimeUnit", |
| 403 |
|
| 404 |
"BackpressureOverflowStrategy", "ParallelFailureHandling", |
| 405 |
|
| 406 |
"Exception", "Throwable", "NullPointerException", "IllegalStateException", "IllegalArgumentException", "MissingBackpressureException", "UndeliverableException", |
| 407 |
"OutOfMemoryError", "StackOverflowError", "NoSuchElementException", "ClassCastException", "CompositeException", |
| 408 |
"RuntimeException", "Error", "TimeoutException", "OnErrorNotImplementedException", |
| 409 |
|
| 410 |
"false", "true", "onNext", "onError", "onComplete", "onSuccess", "onSubscribe", "null", |
| 411 |
|
| 412 |
"ConnectableFlowable", "ConnectableObservable", "Subject", "FlowableProcessor", "Processor", "Scheduler", |
| 413 |
|
| 414 |
"Optional", "CompletionStage", "Collector", "Collectors", "Schedulers", "RxJavaPlugins", "CompletableFuture", |
| 415 |
|
| 416 |
"Object", "Integer", "Long", "Boolean", "LongConsumer", "BooleanSupplier", |
| 417 |
|
| 418 |
"GroupedFlowable", "GroupedObservable", "UnicastSubject", "UnicastProcessor", |
| 419 |
|
| 420 |
"Notification", "Comparable", "Comparator", "Collection", |
| 421 |
|
| 422 |
"SafeSubscriber", "SafeObserver", |
| 423 |
|
| 424 |
"List", "ArrayList", "HashMap", "HashSet", "CharSequence", |
| 425 |
|
| 426 |
"TestSubscriber", "TestObserver", "Class", |
| 427 |
|
| 428 |
"ThreadFactory", "Runnable", "Executor", "ExecutorService", "Executors", "RejectedExecutionException" |
| 429 |
); |
| 430 |
|
| 431 |
static final Set<String> ALWAYS_CODE = new HashSet<>(Arrays.asList( |
| 432 |
"false", "true", "null", "onSuccess", "onNext", "onError", "onComplete", "onSubscribe" |
| 433 |
)); |
| 434 |
|
| 435 |
static final int ERROR_LIMIT = 5000; |
| 436 |
} |