Add experimental support for SkriptDoclet

README.md

@@ -1,21 +1,19 @@
 # skript-db
 
-> Awesome direct database access for Skript
+ > Sensible SQL support for Skript.
-
+---
-## Syntax
 
 ### Expression `Data Source` => `datasource`
+Stores the connection information for a data source. This should be saved to a variable in a
+ `script load` event or manually through an effect command.
 
-This stores the connection information for a data source. This should be saved to a variable in a `script load` event or manually through an effect command.
+ The url format for your database may vary! The example provided uses a MySQL database.
-
-The url format for your database may vary! The example below uses a MySQL database.
-
 #### Syntax
+```
+[the] data(base|[ ]source) [(of|at)] %string%
+```
 
-`[the] data(base|[ ]source) [(of|at)] %string%`
+#### Examples
-
-#### Example
-
 ```
 set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password=12345&useSSL=false"
 ```
@@ -23,50 +21,52 @@ set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password
 ---
 
 ### Effect `Execute Statement`
+Executes a statement on a database and optionally stores the result in a variable. Expressions
+ embedded in the query will be escaped to avoid SQL injection.
 
-Executes a statement on a database and optionally stores the result in a variable. Expressions embedded in the query will be escaped to avoid SQL injection.
+ If a single variable, such as `{test}`, is passed, the variable will be set to the number of
-
+ affected rows.
-If a single variable, such as `{test}`, is passed, the variable will be set to the number of affected rows.
-
-If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list variable in the form `{test::<column name>::<row number>}`
 
+ If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list
+ variable in the form `{test::<column name>::<row number>}`
 #### Syntax
+```
+execute %string% (in|on) %datasource% [and store [[the] (output|result)[s]] (to|in) [the] [var[iable]] %-objects%]
+```
 
-`execute %text% (in|on) %datasource% 
+#### Examples
- [and store [[the] (output|result)[s]] (to|in) [the] [var[iable]] %variable%]`
- 
-#### Example
-
 ```
 execute "select * from table" in {sql} and store the result in {output::*}
+```
+```
 execute "select * from %{table variable}%" in {sql} and store the result in {output::*}
 ```
 
 ---
 
-### Expression `Unsafe Expression` => `text`
+### Expression `Last Data Source Error` => `text`
-
+Stores the error from the last executed statement, if there was one.
-Opts out of automatic SQL injection protection for a specific expression in a statement.
-
 #### Syntax
-
-`unsafe %text%`
-
-#### Example
-
 ```
-execute "select %unsafe {columns variable}% from %{table variable}%" in {sql} and store the result in {output::*}
+[the] [last] (sql|db|data(base|[ ]source)) error
+```
+
+---
+
+### Expression `Unsafe Expression` => `text`
+Opts out of automatic SQL injection protection for a specific expression in a statement.
+#### Syntax
+```
+unsafe %text%
+```
+
+#### Examples
+```
+execute "select %unsafe {columns variable}% from %{table variable}%" in {sql}
+```
+```
 execute unsafe {fully dynamic query} in {sql}
 ```
 
 ---
 
-### Expression `Last Data Source Error` => `text`
-
-Stores the error from the last executed statement, if there was one.
-
-#### Syntax
-
-`[the] [last] (sql|db|data(base|[ ]source)) error`
-
----

build.gradle

@@ -33,3 +33,13 @@ dependencies {
   shadow 'ch.njol:skript:2.2-SNAPSHOT'
   compile 'com.zaxxer:HikariCP:2.6.2'
 }
+
+task buildReadme(type: Javadoc) {
+  source = sourceSets.main.allJava
+  classpath = sourceSets.main.compileClasspath
+  destinationDir = projectDir
+  options.docletpath = [file('tools/skriptdoclet.jar')]
+  options.doclet = 'com.btk5h.skriptdoclet.SkriptDoclet'
+  options.addStringOption('file', 'README.md')
+  options.addStringOption('markdown', '-quiet')
+}

src/main/java/com/btk5h/skriptdb/SkriptDB.java

@@ -35,7 +35,15 @@ import javax.sql.rowset.RowSetProvider;
 
 import ch.njol.skript.Skript;
 import ch.njol.skript.SkriptAddon;
+import ch.njol.skript.doc.Since;
 
+/**
+ * # skript-db
+ *
+ * > Sensible SQL support for Skript.
+ *
+ * @index -1
+ */
 public final class SkriptDB extends JavaPlugin {
 
   private static SkriptDB instance;

src/main/java/com/btk5h/skriptdb/skript/EffExecuteStatement.java

@@ -31,6 +31,23 @@ import ch.njol.skript.lang.VariableString;
 import ch.njol.skript.variables.Variables;
 import ch.njol.util.Kleenean;
 
+/**
+ * Executes a statement on a database and optionally stores the result in a variable. Expressions
+ * embedded in the query will be escaped to avoid SQL injection.
+ *
+ * If a single variable, such as `{test}`, is passed, the variable will be set to the number of
+ * affected rows.
+ *
+ * If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list
+ * variable in the form `{test::<column name>::<row number>}`
+ *
+ * @name Execute Statement
+ * @pattern execute %string% (in|on) %datasource% [and store [[the] (output|result)[s]] (to|in)
+ * [the] [var[iable]] %-objects%]
+ * @example execute "select * from table" in {sql} and store the result in {output::*}
+ * @example execute "select * from %{table variable}%" in {sql} and store the result in {output::*}
+ * @since 0.1.0
+ */
 public class EffExecuteStatement extends Delay {
   static {
     Skript.registerEffect(EffExecuteStatement.class,
@@ -169,7 +186,7 @@ public class EffExecuteStatement extends Delay {
     while (crs.next()) {
       for (int i = 1; i <= columnCount; i++) {
         setVariable(e, baseVariable + meta.getColumnLabel(i).toLowerCase(Locale.ENGLISH)
-                + Variable.SEPARATOR + rowNumber, crs.getObject(i));
+            + Variable.SEPARATOR + rowNumber, crs.getObject(i));
       }
       rowNumber++;
     }

src/main/java/com/btk5h/skriptdb/skript/ExprDBError.java

@@ -9,6 +9,14 @@ import ch.njol.skript.lang.SkriptParser;
 import ch.njol.skript.lang.util.SimpleExpression;
 import ch.njol.util.Kleenean;
 
+/**
+ * Stores the error from the last executed statement, if there was one.
+ *
+ * @name Last Data Source Error
+ * @pattern [the] [last] (sql|db|data(base|[ ]source)) error
+ * @return text
+ * @since 0.1.0
+ */
 public class ExprDBError extends SimpleExpression<String> {
   static {
     Skript.registerExpression(ExprDBError.class, String.class,

src/main/java/com/btk5h/skriptdb/skript/ExprDataSource.java

@@ -11,6 +11,19 @@ import ch.njol.skript.lang.SkriptParser;
 import ch.njol.skript.lang.util.SimpleExpression;
 import ch.njol.util.Kleenean;
 
+/**
+ * Stores the connection information for a data source. This should be saved to a variable in a
+ * `script load` event or manually through an effect command.
+ *
+ * The url format for your database may vary! The example provided uses a MySQL database.
+ *
+ * @name Data Source
+ * @index -1
+ * @pattern [the] data(base|[ ]source) [(of|at)] %string%
+ * @return datasource
+ * @example set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password=12345&useSSL=false"
+ * @since 0.1.0
+ */
 public class ExprDataSource extends SimpleExpression<HikariDataSource> {
   static {
     Skript.registerExpression(ExprDataSource.class, HikariDataSource.class,
@@ -33,7 +46,7 @@ public class ExprDataSource extends SimpleExpression<HikariDataSource> {
     HikariDataSource ds = new HikariDataSource();
     ds.setJdbcUrl(jdbcUrl);
 
-    return new HikariDataSource[] {ds};
+    return new HikariDataSource[]{ds};
   }
 
   @Override

src/main/java/com/btk5h/skriptdb/skript/ExprUnsafe.java

@@ -9,6 +9,16 @@ import ch.njol.skript.lang.SkriptParser;
 import ch.njol.skript.lang.util.SimpleExpression;
 import ch.njol.util.Kleenean;
 
+/**
+ * Opts out of automatic SQL injection protection for a specific expression in a statement.
+ *
+ * @name Unsafe Expression
+ * @pattern unsafe %text%
+ * @return text
+ * @example execute "select %unsafe {columns variable}% from %{table variable}%" in {sql}
+ * @example execute unsafe {fully dynamic query} in {sql}
+ * @since 0.1.0
+ */
 public class ExprUnsafe extends SimpleExpression<String> {
   static {
     Skript.registerExpression(ExprUnsafe.class, String.class, ExpressionType.COMBINED,