[Bleeding] Added support for linking custom CommandExecutor types to a HelpTopicFactory. Fixes BUKKIT-1027

2 files changed, 17 insertions, 8 deletions

diff --git a/src/main/java/org/bukkit/help/HelpMap.java b/src/main/java/org/bukkit/help/HelpMap.java
index f76f4278..c1ce27be 100644
--- a/src/main/java/org/bukkit/help/HelpMap.java
+++ b/src/main/java/org/bukkit/help/HelpMap.java
@@ -34,11 +34,13 @@ public interface HelpMap {
      * Associates a {@link HelpTopicFactory} object with given command base class. Plugins typically
      * call this method during {@code onLoad()}. Once registered, the custom HelpTopicFactory will
      * be used to create a custom {@link HelpTopic} for all commands deriving from the {@code commandClass}
-     * base class.
+     * base class, or all commands deriving from {@link org.bukkit.command.PluginCommand} who's executor
+     * derives from {@code commandClass} base class.
      *
-     * @param commandClass The class for which the custom HelpTopicFactory applies. Must derive from {@link org.bukkit.command.Command}.
+     * @param commandClass The class for which the custom HelpTopicFactory applies. Must derive from
+     * either {@link org.bukkit.command.Command} or {@link org.bukkit.command.CommandExecutor}.
      * @param factory The {@link HelpTopicFactory} implementation to associate with the {@code commandClass}.
-     * @throws IllegalArgumentException Thrown if {@code commandClass} does not derive from Command.
+     * @throws IllegalArgumentException Thrown if {@code commandClass} does not derive from a legal base class.
      */
     public void registerHelpTopicFactory(Class commandClass, HelpTopicFactory factory);
 }
diff --git a/src/main/java/org/bukkit/help/HelpTopicFactory.java b/src/main/java/org/bukkit/help/HelpTopicFactory.java
index 58639510..665372ff 100644
--- a/src/main/java/org/bukkit/help/HelpTopicFactory.java
+++ b/src/main/java/org/bukkit/help/HelpTopicFactory.java
@@ -4,15 +4,22 @@ import org.bukkit.command.Command;
 
 /**
  * A HelpTopicFactory is used to create custom {@link HelpTopic} objects from commands that inherit from a
- * common base class. You can use a custom HelpTopic to change the way all the commands in your plugin display
- * in the help. If your plugin implements a complex permissions system, a custom help topic may also be appropriate.
+ * common base class or have executors that inherit from a common base class. You can use a custom HelpTopic to change
+ * the way all the commands in your plugin display in the help. If your plugin implements a complex permissions system,
+ * a custom help topic may also be appropriate.
  *
  * To automatically bind your plugin's commands to your custom HelpTopic implementation, first make sure all your
- * commands derive from a custom base class (it doesn't have to do anything). Next implement a custom HelpTopicFactory
- * for that accepts your custom command base class and instantiates an instance of your custom HelpTopic from it.
- * Finally, register your HelpTopicFactory against your command base class using the {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)}
+ * commands or executors derive from a custom base class (it doesn't have to do anything). Next implement a custom
+ * HelpTopicFactory that accepts your custom command base class and instantiates an instance of your custom HelpTopic
+ * from it. Finally, register your HelpTopicFactory against your command base class using the {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)}
  * method.
  *
+ * As the help system iterates over all registered commands to make help topics, it first checks to see if there is a
+ * HelpTopicFactory registered for the command's base class. If so, the factory is used to make a help topic rather
+ * than a generic help topic. If no factory is found for the command's base class and the command derives from
+ * {@link org.bukkit.command.PluginCommand}, then the type of the command's executor is inspected looking for a registered
+ * HelpTopicFactory. Finally, if no factory is found, a generic help topic is created for the command.
+ *
  * @param <TCommand> The base class for your custom commands.
  */
 public interface HelpTopicFactory<TCommand extends Command> {