reorganized dependency injection hint and introduced ServicesManager …

…Classes hint
Wolf2323 · Oct 3, 2023 · b73aaef · b73aaef
1 parent be7a884
commit b73aaef
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 67 deletions.
diff --git a/docs/API/Logging.md b/docs/API/Logging.md
@@ -3,6 +3,10 @@ icon: material/text-box-outline
 ---
 @snippet:api-state:stable@
 
+!!! abstract "[ServicesManager](Obtaining-API.md) API Classes"
+    * `org.betonquest.betonquest.api.logger.BetonQuestLoggerFactory`
+---
+
 This page shows you everything you need to know about the BetonQuest logger, no matter if you are working on BetonQuest 
 itself or an integration / addon.
 
@@ -38,54 +42,30 @@ These features were mainly made for BetonQuest, but are also very useful for 3rd
     The naming convention is to use _PascalCase_ for topics.
 
 ## Obtaining a BetonQuestLogger
-
-You should always use dependency injection to provide a `BetonQuestLogger` instance to your class.
-This is a simple example:
-
-
+Use the `BetonQuestLoggerFactory.create()` method to obtain a new BetonQuestLogger instance:
 ```java linenums="1"
-public class MyAddon extends JavaPlugin {
-
-    private BetonQuestLoggerFactory loggerFactory;
-
-    @Override
-    public void onEnable() { //(2)!
-        loggerFactory = Bukkit.getServicesManager().load(BetonQuestLoggerFactory.class); //(1)!
-        new MyFeature(loggerFactory.create(MyFeature.class));
-    }
-}
+BetonQuestLoggerFactory loggerFactory; //(1)!
+BetonQuestLogger logger = loggerFactory.create(MyFeature.class);
 ```
 
-1. Make sure [BetonQuest is loaded](./Overview.md#ensuring-that-betonquest-is-loaded) before using this code!
-2. The earliest point to obtain a `BetonQuestLoggerFactory` is in the `onEnable()` method of your plugin.
+1. Obtained via the ServicesManager, see the [Obtaining API](Obtaining-API.md) page.
 
-```java linenums="1"
-public class MyFeature {
 
-    private final BetonQuestLogger log;
-
-    public MyFeature(final BetonQuestLogger log) {
-        this.log = log;
-    }
-}
-```
-
-
-
-!!! warning "Getting the logger in a class that extends `Plugin`"
-    The methods described above don't work for your plugin's main class (or any other class that extends `Plugin`). 
-    Create the logger instance in the `onEnable()` method instead like this:
+!!! hint "Getting the logger in a class that extends `Plugin`"
+    A class extends `Plugin` can not get an injected `BetonQuestLogger` instance,
+    and can also not use the above `create` method.
+    Therefore, you need to create the logger instance in the `onEnable()` method instead like this:
 
     ```java linenums="1"
     public class BetonQuestAddon extends JavaPlugin {
 
-        private BetonQuestLoggerFactory loggerFactory; 
+        private BetonQuestLoggerFactory betonQuestLoggerFactory; 
         private BetonQuestLogger log;
 
         @Override
         public void onEnable() {
-            loggerFactory = Bukkit.getServicesManager().load(BetonQuestLoggerFactory.class);
-            log = BetonQuestLoggerFactory.create(this);
+            betonQuestLoggerFactory = Bukkit.getServicesManager().load(BetonQuestLoggerFactory.class);
+            log = betonQuestLoggerFactory.create(this);
         }
     }
     ```
@@ -107,31 +87,27 @@ public class MyFeature {
     but it will still cache the instances for the same topic or without a topic.
 
 ## Logging with Topics
-
-
 This is useful if you want to give your log messages a prefix like `(Database)`.
 Mainly _PascalCase_ should be used for topics and they should be short and meaningful to the user. 
 
 ```java linenums="1"
-final BetonQuestLogger logger = loggerFactory.create(MyClass.class, "MyCustomTopic");
+BetonQuestLoggerFactory loggerFactory;
+BetonQuestLogger logger = loggerFactory.create(MyFeature.class, "MyCustomTopic");
 ```
 
 ## Using the BetonQuestLogger
-A BetonQuestLogger will be available as the variable `log` once you [obtained a BetonQuestLogger instance](#obtaining-a-betonquestlogger-instance). 
-It has a bunch of methods for all use cases. Its JavaDocs explain when and how to use these.
+The BetonQuestLogger has a bunch of methods for all use cases. Its JavaDocs explain when and how to use these.
 Make sure to give the JavaDocs a quick read!
 
-The usage then look like this:
+The usage might look like this:
 ````java linenums="1"
-log.info("Hello Log!");
+logger.info("Hello Log!");
 ````
 
 ### Method Overview
-
 All methods come in multiple variants. Always provide a package if possible, as this allows the user to filter log
 messages.
 
-
 | Name                              | Use Case                                                                                                                                                   | Example                                                                                             |
 |-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
 | :shushing_face: Debug             | Used to display internal states or events that may be beneficial for bug-fixing. These messages are only be visible in the debug log.                      | An event has been fired.                                                                            |

diff --git a/docs/API/Obtaining-API.md b/docs/API/Obtaining-API.md
@@ -5,14 +5,14 @@ icon: material/widgets
 
 To obtain the API or a part of the API there are currently two ways, the new way and the legacy way.
 
-## Obtaining the API (new way)
-!!! note "New way"
+## Obtaining the API
+!!! note "New method"
     The new way is the recommended way to get the redesigned parts of the API.  
     It is not yet available for all parts of the API, but will be in the future.
 
 The new API is designed to be modular and extensible.
-To obtain a module of the API you use the `org.bukkit.plugin.ServiceManager`.
-The `ServiceManager` is Bukkit API that allows plugins to provide services to other plugins:
+To obtain a module of the API you use the `org.bukkit.plugin.ServicesManager`.
+The `ServicesManager` is Bukkit API that allows plugins to provide services to other plugins:
 
 ``` Java title="Get a module"
 BetonQuestLoggerFactory loggerFactory = getServer().getServicesManager().load(BetonQuestLoggerFactory.class);
@@ -29,16 +29,52 @@ so usually in the `onLoad` method of your plugin:
 getServer().getServicesManager().register(BetonQuestLoggerFactory.class, new MyLoggerFactory(), this, ServicePriority.Normal);
 ```
 
-## Legacy way
-!!! note "Legacy way"
-    The legacy way is the way that was used before the API was redesigned.
-    It is usually the only way to get those parts of the API that have not been redesigned yet.  
-    It still will be available for the foreseeable future,
-    but you should not use it when writing new code working with API that has already been redesigned.
+### Legacy API
+!!! note "Old method"
+    The legacy API is how you could interact with BetonQuest in the past before the API was redesigned.
+    For most systems that we haven't been able to improve, it is still the only option.  
+    While it will still be available for the foreseeable future,
+    you should not use it when writing new code working with API that has already been redesigned.
 
 The old API uses the `BetonQuest` class as the entry point.
 Most methods are static and can be accessed directly.
 For those methods that need to be called on a `BetonQuest` instance
 you can obtain it by calling the static `BetonQuest.getInstance()` method. 
 
 All the old API is documented on the [Legacy API](Legacy-API.md) page.
+
+## The ServicesManager Hint
+The following hint can be found on many API pages:
+
+!!! abstract "[ServicesManager](Obtaining-API.md) API Classes"
+    * `org.betonquest.betonquest.api.logger.BetonQuestLoggerFactory`
+
+It lists all interfaces that are related to the API described on that page.
+Every one of them can be obtained by using the `ServicesManager` as described below.
+
+## Working with the API
+We recommend that you inject instances you obtained from the `ServicesManager` into your classes when they need them.
+You might want to learn about "Dependency Injection" as a programming technique,
+but as a quick start here's a simple example:
+
+This plugin injects an instance of `BetonQuestLogger` that was created by a `BetonQuestLoggerFactory` into a class implementing some feature.
+
+```java linenums="1"
+public class MyAddon extends JavaPlugin {
+    private BetonQuestLoggerFactory loggerFactory;
+
+    @Override
+    public void onEnable() {
+        loggerFactory = Bukkit.getServicesManager().load(BetonQuestLoggerFactory.class);
+        new MyFeature(loggerFactory.create(MyFeature.class));
+    }
+}
+
+public class MyFeature {
+    private final BetonQuestLogger log;
+
+    public MyFeature(final BetonQuestLogger log) {
+        this.log = log;
+    }
+}
+```
diff --git a/docs/API/Overview.md b/docs/API/Overview.md
@@ -9,7 +9,7 @@ icon: octicons/info-16
     Newly added API's are subject to change and will have an API state assigned to them.
 
     We appreciate any feedback!
-    The [old API page](Legacy-Legacy-API.md) is still available and still explains API that was not reworked yet.
+    The [old API page](Legacy-API.md) is still available and still explains API that was not reworked yet.
 
     ??? question "API States"
         @snippet:api-state:state-explanation@

diff --git a/docs/_snippets/api-state.yml b/docs/_snippets/api-state.yml
@@ -1,20 +1,14 @@
 draft: |-
   ??? warning "API State: `Draft`"
       @snippet:api-state:state-explanation@
-  ---
-
 
 stable: |-
   ??? warning "API State: `Stable`"
       @snippet:api-state:state-explanation@
-  ---
-
 
 unfinished: |-
   ??? warning "API State: `Unfinished`"
       @snippet:api-state:state-explanation@
-  ---
-
 
 state-explanation: |-
   <h3><u>Unfinished</u> </h3>
@@ -36,5 +30,3 @@ state-explanation: |-
   Only bugs and major conceptual problems would lead to more changes.
 
   **This part of the API should be safe to use. We try to keep it compatible with previous versions if changes are needed.**
-  
-  
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -254,10 +254,11 @@ nav:
   - 'API':
       - 'Overview': API/Overview.md
       - 'Obtaining API': API/Obtaining-API.md
-      - 'Legacy API': API/Legacy-API.md
-      - 'ConfigurationFile': API/ConfigurationFile.md
-      - 'Logging': API/Logging.md
-      - 'Schedules': API/Schedules.md
+      - APIs:
+          - 'Legacy API': API/Legacy-API.md
+          - 'Logging': API/Logging.md
+          - 'ConfigurationFile': API/ConfigurationFile.md
+          - 'Schedules': API/Schedules.md
   - 'Participate':
       - 'Overview': Participate/Overview.md
       - 'Donate Money': Participate/Donating-Money.md