Doc improvements suggested by code review

* typos
* removal of some obsolete private docs
* changed section order in readme due to relevance

Author: Zabuzard

README.md

@@ -11,6 +11,11 @@
 
 TJ-Bot is a Discord Bot used on the [Together Java](https://discord.gg/togetherjava) server. It is maintained by the community, anyone can contribute.
 
+# Getting started
+
+* [Documentation](https://github.com/Together-Java/TJ-Bot/wiki): as general entry point to the project
+* [Contributing](https://github.com/Together-Java/TJ-Bot/wiki/Contributing): if you want to improve the bot
+
 # Download
 
 ## Using a build tool
@@ -29,7 +34,7 @@ dependencies {
     implementation 'com.github.Together-Java:TJ-Bot:<tag>'
 }
 ```
-You can replace `<tag>` by either a commit hash (the first 10 characters) or by `-SNAPSHOT` to get the latest version
+You can replace `<tag>` by either a commit hash (the first 10 characters) or by `-SNAPSHOT` to get the latest version.
 
 ### Maven
 
@@ -48,15 +53,10 @@ Then add the dependency:
     <version>[tag]</version>
 </dependency>
 ```
-You can replace `[tag]` by either a commit hash (the first 10 characters) or by `-SNAPSHOT` to get the latest version
+You can replace `[tag]` by either a commit hash (the first 10 characters) or by `-SNAPSHOT` to get the latest version.
 
 ---
 
 ## Jar downloads
 
-Jar downloads are available from the [release section](https://github.com/Together-Java/TJ-Bot/releases).
-
-# Getting started
-
-* [Documentation](https://github.com/Together-Java/TJ-Bot/wiki): as general entry point to the project
-* [Contributing](https://github.com/Together-Java/TJ-Bot/wiki/Contributing): if you want to improve the bot
+Jar downloads are available from the [release section](https://github.com/Together-Java/TJ-Bot/releases).

application/src/main/java/org/togetherjava/tjbot/Application.java

@@ -24,7 +24,6 @@ public enum Application {
      * @param args command line arguments - [the token of the bot, the path to the database]
      */
     public static void main(final String[] args) {
-        // Parse arguments
         if (args.length != 2) {
             throw new IllegalArgumentException("Expected two arguments but " + args.length
                     + " arguments were provided. The first argument must be the token of the bot"
@@ -33,7 +32,6 @@ public static void main(final String[] args) {
         String token = args[0];
         String databasePath = args[1];
 
-        // Start
         try {
             runBot(token, Path.of(databasePath));
         } catch (Exception t) {

application/src/main/java/org/togetherjava/tjbot/DatabaseListener.java

@@ -31,18 +31,13 @@
  * </pre>
  */
 public final class DatabaseListener extends ListenerAdapter {
-    /**
-     * Logger for this class.
-     */
+
     private static final Logger logger = LoggerFactory.getLogger(DatabaseListener.class);
 
-    /**
-     * The database instance used by this command.
-     */
     private final Database database;
 
     /**
-     * Creates a new command listener, using the given database
+     * Creates a new command listener, using the given database.
      *
      * @param database the database to store the key-value pairs in
      */
@@ -78,7 +73,6 @@ public void onMessageReceived(MessageReceivedEvent event) {
      */
     private void handlePutMessage(String message, MessageReceivedEvent event) {
         // !dbput hello Hello World!
-        // Parse message
         logger.info("#{}: Received '!dbput' command", event.getResponseNumber());
         String[] data = message.split(" ", 3);
         if (data.length != 3) {
@@ -90,7 +84,6 @@ private void handlePutMessage(String message, MessageReceivedEvent event) {
         String key = data[1];
         String value = data[2];
 
-        // Save the value in the database
         try {
             database.writeTransaction(ctx -> {
                 StorageRecord storageRecord =
@@ -118,7 +111,6 @@ private void handlePutMessage(String message, MessageReceivedEvent event) {
      */
     private void handleGetMessage(String message, MessageReceivedEvent event) {
         // !dbget hello
-        // Parse message
         logger.info("#{}: Received '!dbget' command", event.getResponseNumber());
         String[] data = message.split(" ", 2);
         if (data.length != 2) {
@@ -129,7 +121,6 @@ private void handleGetMessage(String message, MessageReceivedEvent event) {
         }
         String key = data[1];
 
-        // Retrieve the value from the database
         try {
             Optional<StorageRecord> foundValue = database.read(context -> {
                 return Optional.ofNullable(context.selectFrom(Storage.STORAGE)

application/src/main/java/org/togetherjava/tjbot/PingPongListener.java

@@ -21,9 +21,7 @@
  * </pre>
  */
 public final class PingPongListener extends ListenerAdapter {
-    /**
-     * Logger for this class
-     */
+
     private static final Logger logger = LoggerFactory.getLogger(PingPongListener.class);
 
     /**

application/src/main/java/org/togetherjava/tjbot/db/Database.java

@@ -25,12 +25,9 @@
  */
 public final class Database {
 
-    /**
-     * The DSL context for this database.
-     */
     private final DSLContext dslContext;
     /**
-     * Lock used to implement thread-safety across this class. Any database modifying method should
+     * Lock used to implement thread-safety across this class. Any database modifying method must
      * use this lock.
      */
     private final Lock writeLock = new ReentrantLock();
@@ -44,7 +41,7 @@ public final class Database {
     public Database(String jdbcUrl) throws SQLException {
         SQLiteConfig sqliteConfig = new SQLiteConfig();
         sqliteConfig.enforceForeignKeys(true);
-        // In WAL mode only concurrent writes pose a problem, so we synchronize on those
+        // In WAL mode only concurrent writes pose a problem, so we synchronize those
         sqliteConfig.setJournalMode(SQLiteConfig.JournalMode.WAL);
 
         SQLiteDataSource dataSource = new SQLiteDataSource(sqliteConfig);
@@ -196,11 +193,6 @@ public void writeTransaction(
         });
     }
 
-    /**
-     * Gets the DSL context for this database.
-     *
-     * @return the DSL context
-     */
     private DSLContext getDslContext() {
         return dslContext;
     }