Debian Codegraph @

src/test/java/io/reactivex/rxjava3/validators/JavadocCodesAndLinks.java

raw
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, &#64;see and &#64;throws entries
29 * and &lt;code&gt;&lt;/code&gt; 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 }