/*
 * This file is part of SpongeAPI, licensed under the MIT License (MIT).
 *
 * Copyright (c) SpongePowered <https://www.spongepowered.org>
 * Copyright (c) contributors
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package org.spongepowered.api.event.lifecycle;

import org.spongepowered.api.command.Command;
import org.spongepowered.api.command.manager.CommandFailedRegistrationException;
import org.spongepowered.api.command.manager.CommandMapping;
import org.spongepowered.api.command.registrar.CommandRegistrar;
import org.spongepowered.api.event.GenericEvent;
import org.spongepowered.plugin.PluginContainer;

/**
 * Lifecycle event to indicate when commands should be registered.
 *
 * <p>There are two types command that Sponge will always call an event for:</p>
 *
 * <ul>
 *     <li>Where {@link C} is {@link Command.Raw}; and</li>
 *     <li>Where {@link C} is {@link Command.Parameterized}.</li>
 * </ul>
 *
 * <p>Other plugins may provide a {@link CommandRegistrar} that allows for other
 * types to be registered as commands. These types will be provided by these
 * other plugins.</p>
 *
 * <p>This event will be called whenever the game re-initializes commands, and
 * does not guarantee that any specific engine is running.</p>
 *
 * @param <C> The type of command that is being registered.
 */
public interface RegisterCommandEvent<C> extends GenericEvent<C>, LifecycleEvent {

    /**
     * Registers a command with the appropriate {@link CommandRegistrar}.
     *
     * @param container The {@link PluginContainer}
     * @param command The command to register
     * @param alias The first alias to register for this command
     * @param aliases Any other aliases to register
     * @return The {@link Result}, which contains the {@link CommandMapping} for
     *      this registration, while also allowing for chaining of other command
     *      registrations.
     * @throws CommandFailedRegistrationException if registration failed
     */
    Result<C> register(PluginContainer container, C command, String alias, String... aliases) throws CommandFailedRegistrationException;

    /**
     * The {@link Result} of a command registration, allowing for the chaining
     * of other command registrations, or the retrival of the
     * {@link CommandMapping} generated from the registration that returned this
     * result.
     */
    interface Result<C> {

        /**
         * Registers a command with the appropriate {@link CommandRegistrar}.
         *
         * @param container The {@link PluginContainer}
         * @param command The command to register
         * @param alias The first alias to register for this command
         * @param aliases Any other aliases to register
         * @return The {@link Result}, which contains the {@link CommandMapping} for
         *      this registration, while also allowing for chaining of other command
         *      registrations.
         * @throws CommandFailedRegistrationException if registration failed
         */
        Result<C> register(PluginContainer container, C command, String alias, String... aliases) throws CommandFailedRegistrationException;

        /**
         * The {@link CommandMapping} generated for the previous registration.
         *
         * @return The {@link CommandMapping}
         */
        CommandMapping mapping();

    }

}

@@ -1714,24 +1714,230 @@
 istered.%0A *%0A
+ * %3Cp%3EThis event is generic and the type parameter is %3Cstrong%3Erequired%3C/strong%3E.%0A * This type parameter (%7B@code C%7D) will correspond to the base class or%0A * interface that your command inherits from.%3C/p%3E%0A *%0A
  * %3Cp%3EThere 
@@ -1950,16 +1950,19 @@
 o types 
+of 
 command 
@@ -2003,16 +2003,20 @@
 ent for:
+%0A * 
 %3C/p%3E%0A *%0A
@@ -2034,36 +2034,36 @@
     %3Cli%3EWhere %7B@
-link
+code
  C%7D is %7B@link Co
@@ -2102,20 +2102,20 @@
 Where %7B@
-link
+code
  C%7D is %7B
@@ -2171,20 +2171,210 @@
  %3Cp%3E
-Other plugin
+Commands that have been generated using %7B@link Command#builder()%7D should%0A * be registered during the %7B@code RegisterCommandEvent%3CCommand.Parameterized%3E%7D%0A * event.%3C/p%3E%0A *%0A * %3Cp%3EOther plugins and platform
 s ma
@@ -2414,16 +2414,19 @@
 ar%7D that
+%0A *
  allows 
@@ -2434,19 +2434,16 @@
 or other
-%0A *
  types t
@@ -2490,16 +2490,19 @@
  will be
+%0A *
  provide
@@ -2511,19 +2511,16 @@
 by these
-%0A *
  other p
@@ -2525,16 +2525,65 @@
  plugins
+, consult their documentation for more%0A * details
 .%3C/p%3E%0A *

Clarify the RegisterCommandEvent docs a little bit.