Remove ancient and rather useless incode ejabberd_commands documentation

src/ejabberd_commands.erl

@@ -23,190 +23,6 @@
 %%%
 %%%----------------------------------------------------------------------
 
-%%% @headerfile "ejabberd_commands.hrl"
-
-%%% @doc Management of ejabberd commands.
-%%%
-%%% An ejabberd command is an abstract function identified by a name,
-%%% with a defined number and type of calling arguments and type of
-%%% result, that can be defined in any Erlang module and executed
-%%% using any valid frontend.
-%%%
-%%%
-%%% == Define a new ejabberd command ==
-%%%
-%%% ejabberd commands can be defined and registered in
-%%% any Erlang module.
-%%%
-%%% Some commands are procedures; and their purpose is to perform an
-%%% action in the server, so the command result is only some result
-%%% code or result tuple.  Other commands are inspectors, and their
-%%% purpose is to gather some information about the server and return
-%%% a detailed response: it can be integer, string, atom, tuple, list
-%%% or a mix of those ones.
-%%%
-%%% The arguments and result of an ejabberd command are strictly
-%%% defined.  The number and format of the arguments provided when
-%%% calling an ejabberd command must match the definition of that
-%%% command.  The format of the result provided by an ejabberd command
-%%% must be exactly its definition. For example, if a command is said
-%%% to return an integer, it must always return an integer (except in
-%%% case of a crash).
-%%%
-%%% If you are developing an Erlang module that will run inside
-%%% ejabberd and you want to provide a new ejabberd command to
-%%% administer some task related to your module, you only need to:
-%%% implement a function, define the command, and register it.
-%%%
-%%%
-%%% === Define a new ejabberd command ===
-%%%
-%%% An ejabberd command is defined using the Erlang record
-%%% 'ejabberd_commands'.  This record has several elements that you
-%%% must define. Note that 'tags', 'desc' and 'longdesc' are optional.
-%%%
-%%% For example let's define an ejabberd command 'pow' that gets the
-%%% integers 'base' and 'exponent'. Its result will be an integer
-%%% 'power':
-%%%
-%%% <pre>#ejabberd_commands{name = pow, tags = [test],
-%%%                 desc = "Return the power of base for exponent",
-%%%                 longdesc = "This is an example command. The formula is:\n"
-%%%                 "  power = base ^ exponent",
-%%%                 module = ?MODULE, function = pow,
-%%%                 args = [{base, integer}, {exponent, integer}],
-%%%                 result = {power, integer}}</pre>
-%%%
-%%%
-%%% === Implement the function associated to the command ===
-%%%
-%%% Now implement a function in your module that matches the arguments
-%%% and result of the ejabberd command.
-%%%
-%%% For example the function calc_power gets two integers Base and
-%%% Exponent. It calculates the power and rounds to an integer:
-%%%
-%%% <pre>calc_power(Base, Exponent) ->
-%%%    PowFloat = math:pow(Base, Exponent),
-%%%    round(PowFloat).</pre>
-%%%
-%%% Since this function will be called by ejabberd_commands, it must
-%%% be exported.
-%%% Add to your module:
-%%% <pre>-export([calc_power/2]).</pre>
-%%%
-%%% Only some types of result formats are allowed.
-%%% If the format is defined as 'rescode', then your function must return:
-%%%   ok | true | atom()
-%%% where the atoms ok and true as considered positive answers,
-%%% and any other response atom is considered negative.
-%%%
-%%% If the format is defined as 'restuple', then the command must return:
-%%%   {rescode(), string()}
-%%%
-%%% If the format is defined as '{list, something()}', then the command
-%%% must return a list of something().
-%%%
-%%%
-%%% === Register the command ===
-%%%
-%%% Define this function and put inside the #ejabberd_command you
-%%% defined in the beginning:
-%%%
-%%% <pre>commands() ->
-%%%    [
-%%%
-%%%    ].</pre>
-%%%
-%%% You need to include this header file in order to use the record:
-%%%
-%%% <pre>-include("ejabberd_commands.hrl").</pre>
-%%%
-%%% When your module is initialized or started, register your commands:
-%%%
-%%% <pre>ejabberd_commands:register_commands(commands()),</pre>
-%%%
-%%% And when your module is stopped, unregister your commands:
-%%%
-%%% <pre>ejabberd_commands:unregister_commands(commands()),</pre>
-%%%
-%%% That's all! Now when your module is started, the command will be
-%%% registered and any frontend can access it. For example:
-%%%
-%%% <pre>$ ejabberdctl help pow
-%%%
-%%%   Command Name: pow
-%%%
-%%%   Arguments: base::integer
-%%%              exponent::integer
-%%%
-%%%   Returns: power::integer
-%%%
-%%%   Tags: test
-%%%
-%%%   Description: Return the power of base for exponent
-%%%
-%%% This is an example command. The formula is:
-%%%  power = base ^ exponent
-%%%
-%%% $ ejabberdctl pow 3 4
-%%% 81
-%%% </pre>
-%%%
-%%%
-%%% == Execute an ejabberd command ==
-%%%
-%%% ejabberd commands are mean to be executed using any valid
-%%% frontend.  An ejabberd commands is implemented in a regular Erlang
-%%% function, so it is also possible to execute this function in any
-%%% Erlang module, without dealing with the associated ejabberd
-%%% commands.
-%%%
-%%%
-%%% == Frontend to ejabberd commands ==
-%%%
-%%% Currently there are two frontends to ejabberd commands: the shell
-%%% script {@link ejabberd_ctl. ejabberdctl}, and the XML-RPC server
-%%% ejabberd_xmlrpc.
-%%%
-%%%
-%%% === ejabberdctl as a frontend to ejabberd commands ===
-%%%
-%%% It is possible to use ejabberdctl to get documentation of any
-%%% command. But ejabberdctl does not support all the argument types
-%%% allowed in ejabberd commands, so there are some ejabberd commands
-%%% that cannot be executed using ejabberdctl.
-%%%
-%%% Also note that the ejabberdctl shell administration script also
-%%% manages ejabberdctl commands, which are unrelated to ejabberd
-%%% commands and can only be executed using ejabberdctl.
-%%%
-%%%
-%%% === ejabberd_xmlrpc as a frontend to ejabberd commands ===
-%%%
-%%% ejabberd_xmlrpc provides an XML-RPC server to execute ejabberd commands.
-%%% ejabberd_xmlrpc is a contributed module published in ejabberd-modules SVN.
-%%%
-%%% Since ejabberd_xmlrpc does not provide any method to get documentation
-%%% of the ejabberd commands, please use ejabberdctl to know which
-%%% commands are available, and their usage.
-%%%
-%%% The number and format of the arguments provided when calling an
-%%% ejabberd command must match the definition of that command. Please
-%%% make sure the XML-RPC call provides the required arguments, with
-%%% the specified format. The order of the arguments in an XML-RPC
-%%% call is not important, because all the data is tagged and will be
-%%% correctly prepared by ejabberd_xmlrpc before executing the ejabberd
-%%% command.
-
-%%% TODO: consider this feature:
-%%% All commands are caught. If an error happens, return the restuple:
-%%%   {error, flattened error string}
-%%% This means that ecomm call APIs (ejabberd_ctl, ejabberd_xmlrpc)
-%%% need to allows this. And ejabberd_xmlrpc must be prepared to
-%%% handle such an unexpected response.
-
-
 -module(ejabberd_commands).
 -author('badlop@process-one.net').
 
@@ -312,11 +128,6 @@ code_change(_OldVsn, State, _Extra) ->
 
 -spec register_commands([ejabberd_commands()]) -> ok.
 
-%% @doc Register ejabberd commands.
-%% If a command is already registered, a warning is printed and the
-%% old command is preserved.
-%% A registered command is not directly available to be called through
-%% ejabberd ReST API. It need to be exposed to be available through API.
 register_commands(Commands) ->
     lists:foreach(
       fun(Command) ->
@@ -330,7 +141,6 @@ register_commands(Commands) ->
 
 -spec unregister_commands([ejabberd_commands()]) -> ok.
 
-%% @doc Unregister ejabberd commands.
 unregister_commands(Commands) ->
     lists:foreach(
       fun(Command) ->
@@ -341,14 +151,11 @@ unregister_commands(Commands) ->
 
 -spec list_commands() -> [{atom(), [aterm()], string()}].
 
-%% @doc Get a list of all the available commands, arguments and description.
 list_commands() ->
     list_commands(?DEFAULT_VERSION).
 
 -spec list_commands(integer()) -> [{atom(), [aterm()], string()}].
 
-%% @doc Get a list of all the available commands, arguments and
-%% description in a given API version.
 list_commands(Version) ->
     Commands = get_commands_definition(Version),
     [{Name, Args, Desc} || #ejabberd_commands{name = Name,
@@ -357,7 +164,6 @@ list_commands(Version) ->
 
 -spec get_command_format(atom()) -> {[aterm()], [{atom(),atom()}], rterm()}.
 
-%% @doc Get the format of arguments and result of a command.
 get_command_format(Name) ->
     get_command_format(Name, noauth, ?DEFAULT_VERSION).
 get_command_format(Name, Version) when is_integer(Version) ->
@@ -383,13 +189,11 @@ get_command_format(Name, Auth, Version) ->
 
 -spec get_command_definition(atom()) -> ejabberd_commands().
 
-%% @doc Get the definition record of a command.
 get_command_definition(Name) ->
     get_command_definition(Name, ?DEFAULT_VERSION).
 
 -spec get_command_definition(atom(), integer()) -> ejabberd_commands().
 
-%% @doc Get the definition record of a command in a given API version.
 get_command_definition(Name, Version) ->
     case lists:reverse(
            lists:sort(
@@ -409,7 +213,6 @@ get_commands_definition() ->
 
 -spec get_commands_definition(integer()) -> [ejabberd_commands()].
 
-% @doc Returns all commands for a given API version
 get_commands_definition(Version) ->
     L = lists:reverse(
           lists:sort(
@@ -450,15 +253,11 @@ do_execute_command(Command, Arguments) ->
 
 -spec get_tags_commands() -> [{string(), [string()]}].
 
-%% @spec () -> [{Tag::string(), [CommandName::string()]}]
-%% @doc Get all the tags and associated commands.
 get_tags_commands() ->
     get_tags_commands(?DEFAULT_VERSION).
 
 -spec get_tags_commands(integer()) -> [{string(), [string()]}].
 
-%% @spec (integer) -> [{Tag::string(), [CommandName::string()]}]
-%% @doc Get all the tags and associated commands in a given API version
 get_tags_commands(Version) ->
     CommandTags = [{Name, Tags} ||
 		      #ejabberd_commands{name = Name, tags = Tags}