001    package org.bukkit.help;
002    
003    import org.bukkit.command.Command;
004    
005    /**
006     * A HelpTopicFactory is used to create custom {@link HelpTopic} objects from
007     * commands that inherit from a common base class or have executors that
008     * inherit from a common base class. You can use a custom HelpTopic to change
009     * the way all the commands in your plugin display in the help. If your plugin
010     * implements a complex permissions system, a custom help topic may also be
011     * appropriate.
012     * <p>
013     * To automatically bind your plugin's commands to your custom HelpTopic
014     * implementation, first make sure all your commands or executors derive from
015     * a custom base class (it doesn't have to do anything). Next implement a
016     * custom HelpTopicFactory that accepts your custom command base class and
017     * instantiates an instance of your custom HelpTopic from it. Finally,
018     * register your HelpTopicFactory against your command base class using the
019     * {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)} method.
020     * <p>
021     * As the help system iterates over all registered commands to make help
022     * topics, it first checks to see if there is a HelpTopicFactory registered
023     * for the command's base class. If so, the factory is used to make a help
024     * topic rather than a generic help topic. If no factory is found for the
025     * command's base class and the command derives from {@link
026     * org.bukkit.command.PluginCommand}, then the type of the command's executor
027     * is inspected looking for a registered HelpTopicFactory. Finally, if no
028     * factory is found, a generic help topic is created for the command.
029     *
030     * @param <TCommand> The base class for your custom commands.
031     */
032    public interface HelpTopicFactory<TCommand extends Command> {
033        /**
034         * This method accepts a command deriving from a custom command base class
035         * and constructs a custom HelpTopic for it.
036         *
037         * @param command The custom command to build a help topic for.
038         * @return A new custom help topic or {@code null} to intentionally NOT
039         *     create a topic.
040         */
041        public HelpTopic createTopic(TCommand command);
042    }