add core object type documentation

src/main/java/com/denizenscript/denizencore/flags/FlaggableObject.java

@@ -4,6 +4,22 @@
 
 public interface FlaggableObject extends ObjectTag {
 
+    // <--[ObjectType]
+    // @name FlaggableObject
+    // @prefix None
+    // @base None
+    // @format
+    // N/A
+    //
+    // @description
+    // "FlaggableObject" is a pseudo-ObjectType that represents any type of object that can hold flags,
+    // for use with <@link command flag> or any other flag related tags and mechanisms.
+    //
+    // Just because an ObjectType implements FlaggableObject, does not mean a specific instance of that object type is flaggable.
+    // For example, LocationTag implements FlaggableObject, but a LocationTag-Vector (a location without a world) cannot hold a flag.
+    //
+    // -->
+
     AbstractFlagTracker getFlagTracker();
 
     default AbstractFlagTracker getFlagTrackerForTag() {

src/main/java/com/denizenscript/denizencore/objects/ObjectTag.java

@@ -7,6 +7,20 @@
 
 public interface ObjectTag {
 
+    // <--[ObjectType]
+    // @name ObjectTag
+    // @prefix None
+    // @base None
+    // @format
+    // N/A
+    //
+    // @description
+    // "ObjectTag" is a pseudo-ObjectType that represents the fundamental root of all object types.
+    // If a tag says it returns an "ObjectTag", that means it can return any type of tag
+    // (for example MapTag.get[...] returns an object of ... well, whatever type the value happens to be, so it's simply documented as "ObjectTag").
+    //
+    // -->
+
     /*
      * ObjectTags should contain these two static methods, of which valueOf contains a valid
      * annotation for ObjectFetcher

src/main/java/com/denizenscript/denizencore/objects/core/CustomObjectTag.java

@@ -16,9 +16,13 @@
 
 public class CustomObjectTag implements ObjectTag, Adjustable {
 
-    // <--[language]
-    // @name Custom Objects
-    // @group Object System
+    // <--[ObjectType]
+    // @name CustomObjectTag
+    // @prefix custom
+    // @base ElementTag
+    // @format
+    // The identity format for custom objects is the script name, followed by property syntax listing all fields with their values.
+    //
     // @description
     // Custom objects are custom object types.
     // They use a script basis to create an object similar to the base object types (ListTag, PlayerTags, etc).
@@ -28,9 +32,6 @@ public class CustomObjectTag implements ObjectTag, Adjustable {
     //
     // Custom objects exist for experimental reasons. Do not use these in any real scripts.
     //
-    // These use the object notation "custom@".
-    // The identity format for custom objects is the script name, followed by property syntax listing all fields with their values.
-    //
     // -->
 
     @Fetchable("custom")

src/main/java/com/denizenscript/denizencore/objects/core/DurationTag.java

@@ -15,9 +15,13 @@
  */
 public class DurationTag implements ObjectTag {
 
-    // <--[language]
-    // @name DurationTag Objects
-    // @group Object System
+    // <--[ObjectType]
+    // @name DurationTag
+    // @prefix d
+    // @base ElementTag
+    // @format
+    // The identity format for DurationTags is the number of seconds, followed by an 's'.
+    //
     // @description
     // Durations are a unified and convenient way to get a 'unit of time' throughout Denizen.
     // Many commands and features that require a duration can be satisfied by specifying a number and unit of time, especially command arguments that are prefixed 'duration:', etc.
@@ -31,9 +35,6 @@ public class DurationTag implements ObjectTag {
     //
     // The input of 'instant' or 'infinite' will be interpreted as 0 (for use with commands where instant/infinite logic applies).
     //
-    // These use the object notation "d@".
-    // The identity format for DurationTags is the number of seconds, followed by an 's'.
-    //
     // -->
 
     /////////////////////

src/main/java/com/denizenscript/denizencore/objects/core/ElementTag.java

@@ -25,9 +25,13 @@
 
 public class ElementTag implements ObjectTag {
 
-    // <--[language]
-    // @name ElementTag Objects
-    // @group Object System
+    // <--[ObjectType]
+    // @name ElementTag
+    // @prefix el
+    // @base None
+    // @format
+    // Just the plain text of the element value, no prefix or formatting.
+    //
     // @description
     // ElementTags are simple objects that contain a simple bit of text.
     // Their main usage is within the replaceable tag system,
@@ -55,7 +59,7 @@ public class ElementTag implements ObjectTag {
     // @group Object System
     // @description
     // When "ElementTag(Boolean)" appears in meta documentation, this means the input/output is an ElementTag
-    // (refer to <@link language ElementTag Objects>) that is a boolean.
+    // (refer to <@link objecttype ElementTag>) that is a boolean.
     // Boolean means either a "true" or a "false".
     // -->
 
@@ -64,7 +68,7 @@ public class ElementTag implements ObjectTag {
     // @group Object System
     // @description
     // When "ElementTag(Number)" appears in meta documentation, this means the input/output is an ElementTag
-    // (refer to <@link language ElementTag Objects>) that is an integer number.
+    // (refer to <@link objecttype ElementTag>) that is an integer number.
     // That is, for example: 0, 1, 5, -4, 10002325 or any other number.
     // This does NOT include decimal numbers (like 1.5). Those will be documented as <@link language ElementTag(Decimal)>.
     //
@@ -76,7 +80,7 @@ public class ElementTag implements ObjectTag {
     // @group Object System
     // @description
     // When "ElementTag(Decimal)" appears in meta documentation, this means the input/output is an ElementTag
-    // (refer to <@link language ElementTag Objects>) that is a decimal number.
+    // (refer to <@link objecttype ElementTag>) that is a decimal number.
     // That is, for example: 0, 1, 5, -4, 10002325, 4.2, -18.281241 or any other number.
     // While this is specifically for decimal numbers, the decimal itself is optional (will be assumed as ".0").
     //

src/main/java/com/denizenscript/denizencore/objects/core/ListTag.java

@@ -29,16 +29,10 @@
 public class ListTag implements List<String>, ObjectTag {
 
     // <--[language]
-    // @name ListTag Objects
-    // @group Object System
-    // @description
-    // A ListTag is a list of any data. It can hold any number of objects in any order.
-    // The objects can be of any Denizen object type, including another list.
-    //
-    // List indices start at 1 (so, the tag 'get[1]' gets the very first entry)
-    // and extend to however many entries the list has (so, if a list has 15 entries, the tag 'get[15]' gets the very last entry).
-    //
-    // These use the object notation "li@".
+    // @name ListTag
+    // @prefix li
+    // @base ElementTag
+    // @format
     // The identity format for ListTags is each item, one after the other, in order, separated by a pipe '|' symbol.
     // For example, for a list of 'taco', 'potatoes', and 'cheese', it would be 'li@taco|potatoes|cheese|'
     // A list with zero items in it is simply 'li@',
@@ -48,6 +42,13 @@ public class ListTag implements List<String>, ObjectTag {
     // similarly if an ampersand "&" appears in a list entry, it will be replaced by "&amp".
     // This is a subset of Denizen standard escaping, see <@link language Escaping System>.
     //
+    // @description
+    // A ListTag is a list of any data. It can hold any number of objects in any order.
+    // The objects can be of any Denizen object type, including another list.
+    //
+    // List indices start at 1 (so, the tag 'get[1]' gets the very first entry)
+    // and extend to however many entries the list has (so, if a list has 15 entries, the tag 'get[15]' gets the very last entry).
+    //
     // -->
 
     public static AsciiMatcher needsEscpingMatcher = new AsciiMatcher("&|");

src/main/java/com/denizenscript/denizencore/objects/core/MapTag.java

@@ -16,8 +16,19 @@
 public class MapTag implements ObjectTag, Adjustable {
 
     // <--[language]
-    // @name MapTag Objects
-    // @group Object System
+    // @name MapTag
+    // @prefix map
+    // @base ElementTag
+    // @format
+    // The identity format for MapTags is each key/value pair, one after the other, separated by a pipe '|' symbol.
+    // The key/value pair is separated by a slash.
+    // For example, a map of "taco" to "food", "chicken" to "animal", and "bob" to "person" would be "map@taco/food|chicken/animal|bob/person|"
+    // A map with zero items in it is simply 'map@'.
+    //
+    // If the pipe symbol "|" appears in a key or value, it will be replaced by "&pipe",
+    // a slash "/" will become "&fs", and an ampersand "&" will become "&amp".
+    // This is a subset of Denizen standard escaping, see <@link language Escaping System>.
+    //
     // @description
     // A MapTag represents a mapping of keys to values.
     // Keys are plain text, case-insensitive.
@@ -28,16 +39,6 @@ public class MapTag implements ObjectTag, Adjustable {
     //
     // Order of keys is preserved. Casing in keys is preserved in the object but ignored for map lookups.
     //
-    // These use the object notation "map@".
-    // The identity format for MapTags is each key/value pair, one after the other, separated by a pipe '|' symbol.
-    // The key/value pair is separated by a slash.
-    // For example, a map of "taco" to "food", "chicken" to "animal", and "bob" to "person" would be "map@taco/food|chicken/animal|bob/person|"
-    // A map with zero items in it is simply 'map@'.
-    //
-    // If the pipe symbol "|" appears in a key or value, it will be replaced by "&pipe",
-    // a slash "/" will become "&fs", and an ampersand "&" will become "&amp".
-    // This is a subset of Denizen standard escaping, see <@link language Escaping System>.
-    //
     // -->
 
     public static AsciiMatcher needsEscpingMatcher = new AsciiMatcher("&|/");

src/main/java/com/denizenscript/denizencore/objects/core/QueueTag.java

@@ -20,16 +20,18 @@
 public class QueueTag implements ObjectTag, Adjustable, FlaggableObject {
 
     // <--[language]
-    // @name QueueTag Objects
-    // @group Object System
+    // @name QueueTag
+    // @prefix q
+    // @base ElementTag
+    // @implements FlaggableObject
+    // @format
+    // The identity format for queues is simply the queue ID.
+    //
     // @description
     // A QueueTag is a single currently running set of script commands.
     // This is not to be confused with a script path, which is a single set of script commands that can be run.
     // There can be one, multiple, or zero queues running at any time for any given path.
     //
-    // These use the object notation "q@".
-    // The identity format for queues is simply the queue ID.
-    //
     // This object type is flaggable.
     // Flags on this object type will be reinterpreted as definitions.
     // Flags on queues should just not be used. Use definitions directly.

src/main/java/com/denizenscript/denizencore/objects/core/ScriptTag.java

@@ -76,18 +76,20 @@ public class ScriptTag implements ObjectTag, Adjustable, FlaggableObject {
     // -->
 
     // <--[language]
-    // @name ScriptTag Objects
-    // @group Object System
+    // @name ScriptTag
+    // @prefix s
+    // @base ElementTag
+    // @implements FlaggableObject
+    // @format
+    // The identity format for scripts is simply the script name.
+    //
     // @description
     // A ObjectTag that represents a script container. ScriptTags contain all information inside the script,
     // and can be used in a variety of commands that require script arguments.
     // For example, run and inject will 'execute' script entries inside of a script container when given a matching ScriptTag object.
     //
     // ScriptTags also provide a way to access attributes accessed by the replaceable tag system by using the object fetcher or any other entry point to a ScriptTag object.
     //
-    // These use the object notation "s@".
-    // The identity format for scripts is simply the script name.
-    //
     // This object type is flaggable.
     // Flags on this object type will be stored in the server saves file, under special sub-key "__scripts"
     //

src/main/java/com/denizenscript/denizencore/objects/core/TimeTag.java

@@ -24,15 +24,17 @@
 public class TimeTag implements ObjectTag, Adjustable, FlaggableObject {
 
     // <--[language]
-    // @name TimeTag Objects
-    // @group Object System
-    // @description
-    // A TimeTag represents a real world date/time value.
-    //
-    // These use the object notation "time@".
+    // @name TimeTag
+    // @prefix time
+    // @base ElementTag
+    // @implements FlaggableObject
+    // @format
     // The identity format for TimeTags is "yyyy/mm/dd_hh:mm:ss:mill_offset"
     // So, for example, 'time@2020/05/23_02:20:31:123_-07:00'
     //
+    // @description
+    // A TimeTag represents a real world date/time value.
+    //
     // TimeTags can also be constructed from 'yyyy/mm/dd', 'yyyy/mm/dd_hh:mm:ss', or 'yyyy/mm/dd_hh:mm:ss:mill'.
     // (Meaning: the offset is optional, the milliseconds are optional, and the time-of-day is optional,
     // but if you exclude an optional part, you must immediately end the input there, without specifying more).

src/main/java/com/denizenscript/denizencore/objects/properties/PropertyParser.java

@@ -246,11 +246,23 @@ public static List<Property> getProperties(ObjectTag object) {
         return props;
     }
 
+    // <--[ObjectType]
+    // @name PropertyHolderObject
+    // @prefix None
+    // @base None
+    // @format
+    // N/A
+    //
+    // @description
+    // "PropertyHolderObject" is a pseudo-ObjectType that represents any object that holds properties.
+    //
+    // -->
+
     public static <T extends Adjustable> void registerPropertyTagHandlers(ObjectTagProcessor<T> processor) {
 
         // <--[tag]
         // @attribute <PropertyHolderObject.with[<mechanism>=<value>;...]>
-        // @returns ObjectTag
+        // @returns PropertyHolderObject
         // @group properties
         // @description
         // Returns a copy of the object with mechanism adjustments applied.
@@ -277,7 +289,7 @@ public static <T extends Adjustable> void registerPropertyTagHandlers(ObjectTagP
 
         // <--[tag]
         // @attribute <PropertyHolderObject.with_single[<mechanism>=<value>]>
-        // @returns ObjectTag
+        // @returns PropertyHolderObject
         // @group properties
         // @description
         // Returns a copy of the object with a single mechanism adjustment applied.
@@ -300,7 +312,7 @@ public static <T extends Adjustable> void registerPropertyTagHandlers(ObjectTagP
 
         // <--[tag]
         // @attribute <PropertyHolderObject.with_map[<property-map>]>
-        // @returns ObjectTag
+        // @returns PropertyHolderObject
         // @group properties
         // @description
         // Returns a copy of the object with the MapTag of mechanism adjustments applied.

src/main/java/com/denizenscript/denizencore/tags/core/CustomTagBase.java

@@ -12,7 +12,7 @@ public CustomTagBase() {
         // @returns CustomObjectTag
         // @description
         // Returns a custom object constructed from the input value.
-        // Refer to <@link language Custom Objects>.
+        // Refer to <@link ObjectType CustomObjectTag>.
         // -->
         TagManager.registerTagHandler("custom_object", (attribute) -> {
             if (!attribute.hasContext(1)) {

src/main/java/com/denizenscript/denizencore/tags/core/DurationTagBase.java

@@ -12,7 +12,7 @@ public DurationTagBase() {
         // @returns DurationTag
         // @description
         // Returns a duration object constructed from the input value.
-        // Refer to <@link language DurationTag objects>.
+        // Refer to <@link ObjectType DurationTag>.
         // -->
         TagManager.registerTagHandler("duration", (attribute) -> {
             if (!attribute.hasContext(1)) {

src/main/java/com/denizenscript/denizencore/tags/core/ElementTagBase.java

@@ -12,7 +12,7 @@ public ElementTagBase() {
         // @returns ElementTag
         // @description
         // Returns an element constructed from the input value.
-        // Refer to <@link language ElementTag objects>.
+        // Refer to <@link objecttype ElementTag>.
         // -->
         TagManager.registerTagHandler("element", (attribute) -> {
             if (!attribute.hasContext(1)) {

src/main/java/com/denizenscript/denizencore/tags/core/ListTagBase.java

@@ -13,6 +13,7 @@ public ListTagBase() {
         // @description
         // Returns a list object constructed from the input value.
         // Give no input to create an empty list.
+        // Refer to <@link ObjectType ListTag>.
         // -->
         TagManager.registerTagHandler("list", (attribute) -> {
             if (!attribute.hasContext(1)) {

src/main/java/com/denizenscript/denizencore/tags/core/MapTagBase.java

@@ -13,7 +13,7 @@ public MapTagBase() {
         // @description
         // Returns a map object constructed from the input value.
         // Give no input to create an empty map.
-        // Refer to <@link language MapTag objects>.
+        // Refer to <@link ObjectType MapTag>.
         // -->
         TagManager.registerTagHandler("map", (attribute) -> {
             if (!attribute.hasContext(1)) {

src/main/java/com/denizenscript/denizencore/tags/core/QueueTagBase.java

@@ -19,7 +19,7 @@ public QueueTagBase() {
         // @returns QueueTag
         // @description
         // Returns a queue object constructed from the input value.
-        // Refer to <@link language QueueTag objects>.
+        // Refer to <@link ObjectType QueueTag>.
         // If no input is given, returns the current queue.
         // -->
         TagManager.registerTagHandler(new TagRunnable.RootForm() {

src/main/java/com/denizenscript/denizencore/tags/core/ScriptTagBase.java

@@ -17,7 +17,7 @@ public ScriptTagBase() {
         // @returns ScriptTag
         // @description
         // Returns a script object constructed from the input value.
-        // Refer to <@link language ScriptTag objects>.
+        // Refer to <@link ObjectType ScriptTag>.
         // -->
         TagManager.registerTagHandler(new TagRunnable.RootForm() {
             @Override