Merge remote-tracking branch 'origin/master'

Author: Andre601

Diff for: .github/CONTRIBUTING.md

@@ -20,7 +20,8 @@ This means that some errors you encounter could be the cause of said 3rd party l
 We can't fix issues related to those. If you encounter errors with those, go to the respective repository/site and report the issue.
 
 ### Issue doesn't already exist
-Instead of creating a new issue explaining the same thing as the other one does, better go to the issue and comment on it to proof that it happens on multiple platforms.  
+Before creating an issue, make sure that you checked the issues page for any existing issue of the same type.  
+If one exists, comment on it and provide additional informations.  
 The best way for us to fix errors and issues is by gathering informations to find out why those issues happen. And having multiple issues complaining about the same issue won't help anyone here and only slows the process of fixing it down.
 
 ### Follow the templates
@@ -38,8 +39,8 @@ Javadocs help developers to see what methods they can/should use and what those
 When adding Javadoc comments, follow this Styling choises.
 
 #### Line breaks and paragraphs
-When making a new line, start the new line with `<br>` and __don't__ close it.  
-For paragraphs, keep an empty line in between and then start the new line with a `<p>` (Also don't close it)
+Start a new line with `<br>` (Don't close this tag).  
+Do the same for new paragraphs, but keep an empty line in between the text (And of course use `<p>` instead).
 
 **Example**:
 ```java
@@ -52,18 +53,20 @@ For paragraphs, keep an empty line in between and then start the new line with a
 ```
 
 #### Links
-When linking to other classes or methods, use the full path to it in the `{@link}` option.
+Please always use the full path to a class/method when using `{@link}`
 
 Bad example: `{@link BotBlockAPI}`  
 Good example: `{@link com.andre601.javabotblockapi.BotBlockAPI BotBlockAPI}`
 
-Note the alternative argument used in the good example.  
-A special case is used when linking to a method within the same class. In this case just link the method using #.  
-Example: `{@link #myMethod}`
+We want to point out the alternative text used in the Good example, to display "BotBlockAPI" instead of the path.  
+When linking to a method that is in a separate classm, set the alternative text to `Class.method(option(s))`.
+
+There is an exception for linking, when you link to a method in the same (inner) class.  
+In those cases just link to it by using `{@link #methodName}`
 
 **Note**:  
 Use the `<a href="">` option to link external pages. When doing so also remember to include `target="_blank"`.  
-A link could look like this: `<a href="https://google.com" target="_blank">Google it!</a>` (You have to close it.)
+A link could look like this: `<a href="https://google.com" target="_blank">Google it!</a>` (You have to close the a tag.)
 
 #### param styling
 When the method has parameters, you have to set a description with the `@param` option.  
@@ -78,29 +81,38 @@ Note that the description has to be on a new line.
 ```
 
 #### Since
-When adding new methods to the API, will you need to add a `@since` annotation at the end containing the new version.  
-Usually do only big, breaking changes increase the minor number (`v{major}.{minor}.{build}`) so usually you only increase the build.
+Since annotations are used to mention since what version a method/class is available.  
+The syntax is `@since v{major}.{minor}.{build}` where `{major}` is only changed on huge changes (Entire recodes f.e.), `{minor}` is updated on bigger changes of classes and similar and `{build}` is changed on every other noteworthy change.
+
+In most cases will you only update `{build}` and nothing else. If you're unsure if you can/should update the version, ask a maintainer of this repository for assistance.
 
-Please do NOT edit any already existing `@since` annotation.
+Please **do not change already existing since annotations**. This also includes adding ones to already existing methods/classes.
 
 #### Other Styling
 Please make sure that all text is on the same vertical line (block).  
 This means that when f.e. a `@return` is used, that you have to use two spaces after `@param` instead of one.
 
-#### Example
-Here is an example of a method with all parts:  
+#### Order of the parts
+Here is an example of the different parts being used:  
 ```java
 /**
  * Adds "Bar" to the provided text.
+ * <br>Will throw an error when not providing text.
  * 
  * @param  foo
  *         The text that should get "Bar" added to it.
  *
  * @return The provided String with "Bar" added to it.
  *
+ * @throws IllegalArgumentException
+ *         When the provided String is empty/null.
+ *
  * @since v1.0.0
  */
-public String getFooBar(String foo){
+public String getFooBar(String foo) throws IllegalArgumentException{
+    if(foo.isEmpty())
+        throw new IllegalArgumentException("foo may not be empty");
+        
     return foo + "Bar";
 }
 ```