From c990704418eff950232654ff4ad439e512331cba Mon Sep 17 00:00:00 2001 From: Badlop Date: Thu, 7 May 2020 19:38:12 +0200 Subject: [PATCH] Remove ancient and rather useless incode ejabberd_commands documentation --- src/ejabberd_commands.erl | 201 -------------------------------------- 1 file changed, 201 deletions(-) diff --git a/src/ejabberd_commands.erl b/src/ejabberd_commands.erl index 93ae1fdcc..287a87faf 100644 --- a/src/ejabberd_commands.erl +++ b/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': -%%% -%%% 
#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}}
-%%% -%%% -%%% === 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: -%%% -%%% 
calc_power(Base, Exponent) ->
-%%%    PowFloat = math:pow(Base, Exponent),
-%%%    round(PowFloat).
-%%% -%%% Since this function will be called by ejabberd_commands, it must -%%% be exported. -%%% Add to your module: -%%% 
-export([calc_power/2]).
-%%% -%%% 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: -%%% -%%% 
commands() ->
-%%%    [
-%%%
-%%%    ].
-%%% -%%% You need to include this header file in order to use the record: -%%% -%%% 
-include("ejabberd_commands.hrl").
-%%% -%%% When your module is initialized or started, register your commands: -%%% -%%% 
ejabberd_commands:register_commands(commands()),
-%%% -%%% And when your module is stopped, unregister your commands: -%%% -%%% 
ejabberd_commands:unregister_commands(commands()),
-%%% -%%% That's all! Now when your module is started, the command will be -%%% registered and any frontend can access it. For example: -%%% -%%% 
$ 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
-%%%
-%%% -%%% -%%% == 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}