🚀 Add Structure Support to Docs (#5523)

Author: AyhamAl-Ali

src/main/java/ch/njol/skript/Skript.java

@@ -1438,7 +1438,7 @@ public boolean check(final @Nullable ExpressionInfo<?, ?> i) {
 	// ================ EVENTS ================
 
 	private static final List<StructureInfo<? extends Structure>> structures = new ArrayList<>(10);
-	
+
 	/**
 	 * Registers an event.
 	 * 
@@ -1469,7 +1469,7 @@ public static <E extends SkriptEvent> SkriptEventInfo<E> registerEvent(String na
 
 		String[] transformedPatterns = new String[patterns.length];
 		for (int i = 0; i < patterns.length; i++)
-			transformedPatterns[i] = "[on] " + SkriptEvent.fixPattern(patterns[i]) + " [with priority (lowest|low|normal|high|highest|monitor)]";
+			transformedPatterns[i] = "[on] " + SkriptEvent.fixPattern(patterns[i]) + SkriptEventInfo.EVENT_PRIORITY_SYNTAX;
 
 		SkriptEventInfo<E> r = new SkriptEventInfo<>(name, transformedPatterns, c, originClassPath, events);
 		structures.add(r);

src/main/java/ch/njol/skript/doc/HTMLGenerator.java

@@ -36,8 +36,10 @@
 import com.google.common.collect.Lists;
 import com.google.common.io.Files;
 import org.apache.commons.lang.StringUtils;
-import org.apache.commons.lang.WordUtils;
 import org.eclipse.jdt.annotation.Nullable;
+import org.skriptlang.skript.lang.entry.EntryData;
+import org.skriptlang.skript.lang.entry.EntryValidator;
+import org.skriptlang.skript.lang.structure.StructureInfo;
 
 import java.io.File;
 import java.io.IOException;
@@ -50,6 +52,7 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
 
 /**
  * Template engine, primarily used for generating Skript documentation
@@ -274,6 +277,21 @@ else if (!filesInside.getName().matches("(?i)(.*)\\.(html?|js|css|json)")) {
 				String genType = genParams[0];
 				boolean isDocsPage = genType.equals("docs");
 
+				if (genType.equals("structures") || isDocsPage) {
+
+					for (Iterator<StructureInfo<?>> it = sortedAnnotatedIterator(
+							(Iterator) Skript.getStructures().stream().filter(structure -> structure.getClass() == StructureInfo.class).iterator());
+							it.hasNext(); ) {
+
+						StructureInfo<?> info = it.next();
+						assert info != null;
+						if (info.c.getAnnotation(NoDoc.class) != null)
+							continue;
+						String desc = generateAnnotated(descTemp, info, generated.toString(), "Structure");
+						generated.append(desc);
+					}
+				}
+
 				if (genType.equals("expressions") || isDocsPage) {
 					for (Iterator<ExpressionInfo<?,?>> it = sortedAnnotatedIterator((Iterator) Skript.getExpressions()); it.hasNext(); ) {
 						ExpressionInfo<?,?> info = it.next();
@@ -496,6 +514,25 @@ private String generateAnnotated(String descTemp, SyntaxElementInfo<?> info, @Nu
 		// New Elements
 		desc = handleIf(desc, "${if new-element}", NEW_TAG_PATTERN.matcher((since != null ? since.value() : "")).find());
 
+		// Structure - EntryData
+		if (info instanceof StructureInfo) {
+			EntryValidator entryValidator = ((StructureInfo<?>) info).entryValidator;
+			List<EntryData<?>> entryDataList = new ArrayList<>();
+			if (entryValidator != null)
+				entryDataList.addAll(entryValidator.getEntryData());
+
+			// TODO add type of entrydata like boolean/string/section etc.
+			desc = handleIf(desc, "${if structure-optional-entrydata}", entryValidator != null);
+			desc = desc.replace("${element.structure-optional-entrydata}", entryValidator == null ? "" : Joiner.on(", ").join(entryDataList.stream().filter(EntryData::isOptional).map(EntryData::getKey).collect(Collectors.toList())));
+
+			desc = handleIf(desc, "${if structure-required-entrydata}", entryValidator != null);
+			desc = desc.replace("${element.structure-required-entrydata}", entryValidator == null ? "" : Joiner.on(", ").join(entryDataList.stream().filter(entryData -> !entryData.isOptional()).map(EntryData::getKey).collect(Collectors.toList())));
+		} else {
+			desc = handleIf(desc, "${if structure-optional-entrydata}", false);
+			desc = handleIf(desc, "${if structure-required-entrydata}", false);
+
+		}
+
 		// Type
 		desc = desc.replace("${element.type}", type);
 
@@ -604,6 +641,9 @@ private String generateEvent(String descTemp, SkriptEventInfo<?> info, @Nullable
 		// Return Type
 		desc = handleIf(desc, "${if return-type}", false);
 
+		desc = handleIf(desc, "${if structure-optional-entrydata}", false);
+		desc = handleIf(desc, "${if structure-required-entrydata}", false);
+
 		// Generate Templates
 		List<String> toGen = Lists.newArrayList();
 		int generate = desc.indexOf("${generate");
@@ -623,6 +663,7 @@ private String generateEvent(String descTemp, SkriptEventInfo<?> info, @Nullable
 			for (String line : getDefaultIfNullOrEmpty(info.patterns, "Missing patterns.")) {
 				assert line != null;
 				line = cleanPatterns(line);
+				line = line.replace(SkriptEventInfo.EVENT_PRIORITY_SYNTAX, ""); // replace priority syntax in event syntaxes
 				String parsed = pattern.replace("${element.pattern}", line);
 				patterns.append(parsed);
 			}
@@ -704,6 +745,9 @@ private String generateClass(String descTemp, ClassInfo<?> info, @Nullable Strin
 		// Return Type
 		desc = handleIf(desc, "${if return-type}", false);
 
+		desc = handleIf(desc, "${if structure-optional-entrydata}", false);
+		desc = handleIf(desc, "${if structure-required-entrydata}", false);
+
 		// Generate Templates
 		List<String> toGen = Lists.newArrayList();
 		int generate = desc.indexOf("${generate");
@@ -788,6 +832,9 @@ private String generateFunction(String descTemp, JavaFunction<?> info) {
 		// Type
 		desc = desc.replace("${element.type}", "Function");
 
+		desc = handleIf(desc, "${if structure-optional-entrydata}", false);
+		desc = handleIf(desc, "${if structure-required-entrydata}", false);
+
 		// Generate Templates
 		List<String> toGen = Lists.newArrayList();
 		int generate = desc.indexOf("${generate");

src/main/java/ch/njol/skript/lang/SkriptEventInfo.java

@@ -28,6 +28,8 @@
 import ch.njol.skript.SkriptAPIException;
 
 public final class SkriptEventInfo<E extends SkriptEvent> extends StructureInfo<E> {
+
+	public static final String EVENT_PRIORITY_SYNTAX = " [with priority (lowest|low|normal|high|highest|monitor)]";
 
 	public Class<? extends Event>[] events;
 	public final String name;

src/main/java/ch/njol/skript/structures/StructFunction.java

@@ -46,6 +46,7 @@
 @Examples({
 	"function sayMessage(message: text):",
 	"\tbroadcast {_message} # our message argument is available in '{_message}'",
+	"",
 	"local function giveApple(amount: number) :: item:",
 	"\treturn {_amount} of apple"
 })

src/main/java/ch/njol/skript/structures/StructOptions.java

@@ -49,11 +49,13 @@
 @Examples({
 	"options:",
 	"\tno_permission: You're missing the required permission to execute this command!",
+	"",
 	"command /ping:",
 	"\tpermission: command.ping",
 	"\tpermission message: {@no_permission}",
 	"\ttrigger:",
 	"\t\tmessage \"Pong!\"",
+	"",
 	"command /pong:",
 	"\tpermission: command.pong",
 	"\tpermission message: {@no_permission}",

src/main/java/ch/njol/skript/structures/StructVariables.java

@@ -68,6 +68,7 @@
 	"variables:",
 		"\t{joins} = 0",
 		"\t{balance::%player%} = 0",
+	"",
 	"on join:",
 		"\tadd 1 to {joins}",
 		"\tmessage \"Your balance is %{balance::%player%}%\"",

src/main/java/org/skriptlang/skript/lang/structure/Structure.java

@@ -51,7 +51,6 @@
  * The values of these entries can be obtained by parsing the Structure's sub{@link Node}s
  *  through registered {@link EntryData}.
  */
-// TODO STRUCTURE add Structures to docs
 public abstract class Structure implements SyntaxElement, Debuggable {
 
 	/**