Skip to content

Javadoc mistakes to look for #4535

Open
@akarnokd

Description

@akarnokd

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)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions