Add some meta for Assignment Scripts and dObjects

src/main/java/net/aufdemrand/denizen/objects/dMaterial.java

@@ -118,7 +118,7 @@ public static enum dMaterials { WHITE_WOOL, ORANGE_WOOL, MAGENTA_WOOL, LIGHT_BLU
     public final static dMaterial BIRCH_LEAVES = new dMaterial(Material.LEAVES, 2).forceIdentifyAs("BIRCH_LEAVES");
     public final static dMaterial JUNGLE_LEAVES = new dMaterial(Material.LEAVES, 3).forceIdentifyAs("JUNGLE_LEAVES");
 
-    // TODO: Need to find a way to handle horizontal logs/etc. Should they be a different material?
+    // TODO: Need to find a way to handle horizontal logs/etc. Should they be a different dMaterial?
     public final static dMaterial OAK_LOG = new dMaterial(Material.LOG, 0).forceIdentifyAs("OAK_LOG");
     public final static dMaterial SPRUCE_LOG = new dMaterial(Material.LOG, 1).forceIdentifyAs("SPRUCE_LOG");
     public final static dMaterial BIRCH_LOG = new dMaterial(Material.LOG, 2).forceIdentifyAs("BIRCH_LOG");

src/main/java/net/aufdemrand/denizen/objects/dObject.java

@@ -2,6 +2,140 @@
 
 import net.aufdemrand.denizen.tags.Attribute;
 
+// <--[language]
+// @name dObject
+// @description
+// dObjects are a system put into place by Denizen that make working with things, or 'objects',
+// in Minecraft and Denizen easier. Many parts of scripts will require some kind of object as an
+// argument, identifier/type, or such as in world events, part of an event name. The dObjects notation
+// system helps both you and Denizen know what type of objects are being referenced and worked with.
+//
+// So when should you use dObjects? In arguments, event names, replaceable tags, configs, flags, and
+// more! If you're just a beginner, you've probably been using them without even realizing it!
+//
+// dObject is a broader term for a 'type' of object that more specifically represents something,
+// such as a dLocation or dScript, often times just referred to as a 'location' or 'script'. Denizen
+// employs many object types that you should be familiar with. You'll notice that many times objects
+// are reference with their 'dObject notation' which is in the format of 'x@', the x being the specific
+// notation of an object type. Example: player objects use the p@ notation, and locations use l@.
+// The use of this notation is encouraged, but not always required.
+//
+// Let's take the tag system, for example. It uses the dObjects system pretty heavily. For instance,
+// every time you use <player.name> or <npc.id>, you're using a dObject, which brings us to a simple
+// clarification: Why <player.name> and not <p@player.name>? That's because Denizen allows Players,
+// NPCs and other 'in-context objects' to be linked to certain scripts. In short, <player> already
+// contains a reference to a specific player, such as the player that died in a world event 'on player dies'.
+// <p@player.name> would incorrectly reference the player named 'name', however this format is often
+// used to help with usage of a tag, simply indicating 'any player object'.
+//
+// dObjects can be used to CREATE new instances of objects, too! Though not all types allow 'new'
+// objects to be created, many do, such as dItems. With the use of tags, it's easy to reference a specific
+// item, say -- an item in the Player's hand -- items are also able to use a constructor to make a new item,
+// and say, drop it in the world. Take the case of the command/usage '- drop i@diamond_ore'. The item object
+// used is a brand new diamond_ore, which is then dropped by the command to a location of your choice -- just
+// specify an additional location argument.
+//
+// There's a great deal more to learn about dObjects, so be sure to check out each object type for more
+// specific information. While all dObjects share some features, many contain goodies on top of that!
+//
+// Here's an overview of each object type that is implemented by the Denizen core:
+//
+// + ----- dPlayer ----- +
+// | object notation: p@    can reference unique objects: yes    can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   p@<player_name>  - fetches an online or offline player with 'player_name'
+//
+// + ----- dNPC ---------+
+// | object notation: n@    can reference unique objects: yes    can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   n@<npc_id> - fetches the NPC with the specified id
+// |   n@<npc_name> - fetches the first NPC found with the specified name
+//
+// + ----- dLocation ----+
+// | object notation: l@    can reference unique objects: no     can be notable: yes
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   l@<x>,<y>,<z>,<world_name> - fetches a specific location
+// |   l@<notable_location_name> - fetches the location that has been 'noted' with the specified id
+//
+// + ----- dEntity ------+
+// | object notation: e@    can reference unique objects: yes    can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   e@<entity_type> - fetches a new entity with the specified type as implemented by bukkit's entity type enumeration
+// |   e@<entity_script_name> - fetches a new custom entity as specified by the referenced entity script (soon)
+// |   e@<entity_id> - fetches the entity that has the (temporary) entity id set by bukkit
+// |   e@random - fetches a new, random entity
+//
+// + ----- dItem --------+
+// | object notation: i@    can reference unique objects: no     can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   i@<material_name> - fetches a new item of the specified material
+// |   i@<material_name>,<data> - fetches a new item with the specified data
+// |   i@<item_entity_id> - fetches an item that is laying on the ground in a world by its bukkit entity_id
+// |   i@<item_script_name> - fetches a new custom item as specified by the referenced item script
+//
+// + ----- dWorld -------+
+// | object notation: w@    can reference unique objects: yes     can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   w@<world_name> - fetches the world with the specified name
+//
+// + ----- dColor -------+
+// | object notation: c@    can reference unique objects: no      can be notable: soon
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   c@<color_name> - fetches a named color, as implemented by bukkit's color enumeration
+// |   c@<r>,<g>,<b> - fetches a color make of the specified r,g,b values
+// |   c@random - fetches a random color
+//
+// + ----- dCuboid ------+
+// | object notation: cu@   can reference unique objects: no      can be notable: yes
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   cu@<position_1>|<position_2> - fetches a new cuboid with the specified locations as 'pos1' and 'pos2'
+// |   cu@<notable_cuboid_name> - fetches the cuboid that has been 'noted' with the specified id
+//
+// + ----- dInventory ---+
+// | object notation: in@   can reference unique objects: yes     can be notable: soon
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   in@player[<player_name/object>] - fetches the specified Player's inventory
+// |   in@npc[<npc_id/object>] - fetches the specified NPC's inventory
+// |   in@entity[<entity_object>] - fetches the specified object's inventory, such as a Player, NPC, or Mule
+// |   in@location[<location_object>] - fetches the contents of a chest or other 'inventory' block
+// |   in@<notable_inventory_name> - fetches the inventory that has been 'noted' with the specified id
+// |   in@<inventory_script_name> - fetches a new custom inventory as specified by the referenced inventory script
+//
+// + ----- dMaterial ----+
+// | object notation: m@    can reference unique objects: no      can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   m@<material_name> - fetches the material as specified by bukkit's material enumeration
+// |   m@<material_name>,<data> - fetches the material as specified by bukkit's material enumeration with specified data
+// |   m@<data_variety_material> - fetches the material specified by Denizen's 'data variety' dMaterials
+// |   m@random - fetches a random material
+//
+// + ----- dList -------+
+// | object notation: li@,fl@  can reference unique objects: yes  can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   li@<items|...> - fetches a new list with the elements specified, seperated by a pipe (|) character
+// |   li@val[<items|...>] - slightly more verbose, but tag friendly way to fetch a new list (allows periods)
+// |   fl@<server_flag_name> - fetches the flag list value of the specified server flag, as a dList
+// |   fl[<player_object/npc_object]@<flag_name> - fetches the flag list value of the specified player/npc's flag, as a dList
+//
+// + ----- dScript -------+
+// | object notation: s@    can reference unique objects: yes     can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   w@<script_container_name> - fetches the script container with the specified name
+//
+// + ----- Duration ------+
+// | object notation: d@    can reference unique objects: no      can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   d@<duration> - fetches a duration object with the specified amount of time
+// |   d@<low>|<high> - fetches a duration that is randomly selected between the specified 'low' and 'high'
+//
+// + ----- Element ------+
+// | object notation: el@   can reference unique objects: no      can be notable: no
+// | constructors: ( <>'s represent non-static information and are not literal)
+// |   el@<value> - fetches an element with the specified value
+// |   el@val[<value>] - slightly more verbose, but tag friendly way to fetch a new element (allows periods)
+//
+// -->
+
 public interface dObject {
 
     /**

src/main/java/net/aufdemrand/denizen/scripts/containers/core/AssignmentScriptContainer.java

@@ -3,6 +3,44 @@
 import net.aufdemrand.denizen.scripts.containers.ScriptContainer;
 import org.bukkit.configuration.ConfigurationSection;
 
+// <--[language]
+// @name Assignment Script-Containers
+// @description
+// Assignment script-containers provide functionality to NPCs by 'assignment' of the container. Assignment
+// scripts are meant to be used when customizing the normal behavior of NPCs. This can be used on a 'per-npc' basis,
+// but the encouraged approach is to design assignment scripts in a way that they can be used for multiple NPCs,
+// perhaps with the use of constants or flags to determine specific information required by the scripts.
+
+// Features unique to assignment script-containers include 'actions', 'constants', and 'interact script' assignment.
+// Like any script, the ability to run local utility scripts can be accomplished as well. This allows fully
+// interactive NPCs to be built purely with Assignment Scripts, and for advanced situations, world scripts and
+// interact scripts can provide more functionailty.
+
+// Basic structure of an assignment script:
+// <code>
+// Assignment script container name:
+//   type: assignment
+//
+//   actions:
+//     on <action>:
+//     - ...
+//
+//   constants:
+//     <constant name>: <value>
+//     <constant list>:
+//     - ...
+//
+//   interact scripts:
+//   - <priority> <interact script name>
+//   - ...
+//
+//   </code>
+//
+// Unlike other script containers, all part of an assignment script are optional. The three features provided can be
+// used together, but do not require one another.
+
+// -->
+
 public class AssignmentScriptContainer extends ScriptContainer {
 
     public AssignmentScriptContainer(ConfigurationSection configurationSection, String scriptContainerName) {