Oshi: Add @Documented to annotations

[dbwiddis]

I'm marking this issue for first-timers-only. That means that I will only accept a PR for this one from someone who's never contributed to open source before. This one is easy (but don't make that statement make you feel bad if you have a hard time with it, there's more to contributing to open source than changing lines of code, especially if it's your first time). I'll hold your hand through this if you need me to. :-)

In 4.6.0, annotations were added to indicate thread safety (or lack thereof) for OSHI classes. Due to Java 9 (and later) compatibility concerns, these annotations were defined in the oshi.annotation.concurrent package rather than a dependency on a javax.* path. Unfortunately, these annotations were not declared as @Documented, which means they don't show up in the Javadocs.

Your mission, should you choose to accept it, is to declare the three new annotations as @Documented.

Here are the steps to get a PR merged here.

• Read the CONTRIBUTING file for reference. We'll follow those steps, and I'll walk you through anything you don't understand.
• Fork the project to your own GitHub account, make a local clone, and create a branch for your submission.
• In the three annotation class declarations in the oshi.annotation.concurrent package, add @Documented on the line immediately preceding public @interface.
• Commit your changes, push to to your GitHub fork, and create a Pull Request
• Respond to the usually minor comments on code review
• Celebrate! :tada:

[Bob160]

Hello @dbwiddis. May I take up this issue with your help?

[dbwiddis]

It's all yours, @Bob160 !

[Bob160]

Hello @dbwiddis , ran mvn test but had errors.

Trying to install jdk and mavin before running the test again and then proceeding from there.

What do you think? Am I on the right path?

Thanks

[dbwiddis]

You're on the right path! You actually don't need to install Maven if you don't want to because OSHI is packaged with a maven wrapper that will download it... from the root directory of OSHI just run the "mvnw.cmd" batch file. So mvnw test should work; if not, try ./mvnw test.

You can, of course, also install maven, and make sure it's added to your PATH.

Finally, a note: I know running mvn test is in the instructions but since all you're updating is documentation, it won't change the test files. So it's a good learning exercise to run it, but a better test would be to run mvn javadoc:javadoc and inspect the output files to be sure the annotation is added!

[dbwiddis]

Hey @Bob160 it looks like someone jumped the line and did this already. If you don't mind, I'll merge their contribution, but would be happy to keep working with you to find another change you can make... okay?

[Bob160]

Hello @dbwiddis , not a problem at all.
Looking forward to working with you to find and solve other issues.
Cheers

[dbwiddis]

Here's one for you @Bob160 ... won't make it a new issue so just you can work on it! Add the final annotation to this inner class:
https://scrutinizer-ci.com/g/oshi/oshi/issues/master/files/oshi-core/src/main/java/oshi/util/platform/unix/solaris/KstatUtil.java?selectedLabels%5B0%5D=18&orderField=path&order=asc&honorSelectedPaths=0

[Bob160]

Hi @dbwiddis , sorry, I'm lost!
I don't seem to understand what the task is about.
Your guidance would be appreciated.
Thanks

[dbwiddis]

The task is to edit the definition of the KstatChain class (KstatUtil class line 74). It's currently public static class. It should be public static final class.

[Bob160]

How do I get to edit the code on that platform? Tried to no avail. Do I need an account to be able to edit?

[dbwiddis]

That platform is simply for reporting. You have to make the edits on your own fork. Take a look at this description of the Triangle Workflow that we (and most github projects) use.

The first thing you need to do is go to the main project page and look for the link to "Fork" the repository. This will create a copy of the repository at your github account: https://github.com/Bob160/oshi.

Next you will "clone" that fork to your local machine. You install git on your machine, and use the git clone https://github.com/Bob160/oshi.git command.

Edit the code locally, then use the 'git commit' and 'git push' commands to push your changes up to your github fork. Then from the fork, click the button to "submit a pull request".

[Bob160]

@dbwiddis Thank you very much for your prompt response and for all the information.

I just submitted a pull request.

Looking forward to working on more issues with you.

Thanks