Javadoc mistakes to look for

[akarnokd]

trafficstars

From this comment:

• parameter names change in the code but the javadocs still refer to the old names
• potential exceptions change in the code and the javadocs aren't updated to match
• missing backpressure / scheduler / since-annotations, and outdated information in each of these
• changing things from consonant- to vowel-sound-starting, doing a search-and-replace, and not replacing "a" with "an" or vice-versa to match. Also, sometimes changing singulars to plurals or vice-versa by search-and-replace, which causes its own set of grammatical headaches.
• if you see any documentation that uses the passive voice, you can almost always make it clearer and less prone to misinterpretation by rewriting it in the active voice
• URLs for marble diagrams are copy-and-pasted, the name of the operator is changed, but the width/height values in the img tag are not, so that the right image appears but in the wrong dimensions (there were a couple of these in the javadocs last I looked)

[vanniktech]

I noticed in #4589 that sometimes there's an error where the javadoc starts with /** Returns an Observable however the return type of the method is no longer an Observable. (e.g. https://github.com/ReactiveX/RxJava/pull/4589/files#diff-dce8212f1f82c8f48cae503990587755R7707)

[akarnokd]

Might be possible to write a check for this but currently the source file is not parsed but only string-contains checked.

[MiSikora]

I see that only static methods are annotated with @NonNull. Is there a reason behind it or can it be extended to member functions like map() in a PR?

[akarnokd]

@MiSikora IntelliJ/Kotlin users are mostly affected by their lack, or sometimes their presence so I can't give you a definite answer from a Eclipse/Java perspective.