JetBrains / java-annotations

Annotations for JVM-based languages.
Apache License 2.0
404 stars 47 forks source link

Please add missing documentation/rationale #14

Closed martinandersson closed 5 years ago

martinandersson commented 5 years ago

I read through the README, and I can not find one line that says why I should use this project. What's the purpose? This needs to be clarified, preferably with at least one example.

On top of that, IntelliJ disturbs me in my work process with a pop up message indicating that not attaching these annotations (whatever "attaching" means, but I suppose, it will add a dependency in my build file) will sort of cloak away "issues".

So that's like two errors, although granted, the latter should be an issue filed somewhere else.

But one must wonder, did you simply expect that people click on "attach" buttons without any knowledge what these added dependencies actually do? I mean, it seems to even be hard to google this information. I didn't succeed. Hey, maybe that is what developers do these days and it's just me trying to keep my project not locked in to a particular IDE and actively trying to minimize the number of dependencies (and thus, complexity) in my project.

I am sure this - as well as some ten thousand more libraries and frameworks and "analyzers" that could be added as a dependency - has some perceived value to it. But it must be explained or else I feel like the whole world has gone batshit crazy to be honest. LOL! =)

amaembo commented 5 years ago

Hello!

This repository contains annotations only, so only problems related to annotations themselves (not IDE behavior) should be reported here. IntelliJ issues should be reported to IntelliJ bugtracker: https://youtrack.jetbrains.com/issues

I read through the README, and I can not find one line that says why I should use this project.

README.MD says currently:

They serve as an additional documentation and can be interpreted by IDEs and static analysis tools to improve code analysis.

It sounds pretty clear to me.