Add description of arguments for API functions hook_info and hook_infolist

4 files changed, 77 insertions, 61 deletions

diff --git a/doc/en/autogen/plugin_api/completions.txt b/doc/en/autogen/plugin_api/completions.txt
index 02f0d0b6e..5fefd5447 100644
--- a/doc/en/autogen/plugin_api/completions.txt
+++ b/doc/en/autogen/plugin_api/completions.txt
@@ -1,6 +1,7 @@
 [width="65%",cols="^1,^2,8",options="header"]
 |========================================
 | Plugin | Name | Description
+
 | alias | alias | list of aliases
 
 | aspell | aspell_langs | list of supported langs for aspell
diff --git a/doc/en/autogen/plugin_api/infolists.txt b/doc/en/autogen/plugin_api/infolists.txt
index 69dcbbab0..c49bb5bbb 100644
--- a/doc/en/autogen/plugin_api/infolists.txt
+++ b/doc/en/autogen/plugin_api/infolists.txt
@@ -1,58 +1,59 @@
-[width="65%",cols="^1,^2,8",options="header"]
+[width="100%",cols="^1,^2,5,5,5",options="header"]
 |========================================
-| Plugin | Name | Description
-| alias | alias | list of aliases
+| Plugin | Name | Description | Pointer | Arguments
 
-| irc | irc_channel | list of channels for an IRC server
+| alias | alias | list of aliases | alias pointer (optional) | alias name (can start or end with "*" as joker) (optional)
 
-| irc | irc_ignore | list of IRC ignores
+| irc | irc_channel | list of channels for an IRC server | channel pointer (optional) | server name
 
-| irc | irc_nick | list of nicks for an IRC channel
+| irc | irc_ignore | list of IRC ignores | ignore pointer (optional) | -
 
-| irc | irc_server | list of IRC servers
+| irc | irc_nick | list of nicks for an IRC channel | nick pointer (optional) | server,channel,nick (channel and nick are optional)
 
-| logger | logger_buffer | list of logger buffers
+| irc | irc_server | list of IRC servers | server pointer (optional) | server name (can start or end with "*" as joker) (optional)
 
-| lua | lua_script | list of scripts
+| logger | logger_buffer | list of logger buffers | logger pointer (optional) | -
 
-| perl | perl_script | list of scripts
+| lua | lua_script | list of scripts | script pointer (optional) | script name (can start or end with "*" as joker) (optional)
 
-| python | python_script | list of scripts
+| perl | perl_script | list of scripts | script pointer (optional) | script name (can start or end with "*" as joker) (optional)
 
-| relay | relay | list of relay clients
+| python | python_script | list of scripts | script pointer (optional) | script name (can start or end with "*" as joker) (optional)
 
-| ruby | ruby_script | list of scripts
+| relay | relay | list of relay clients | relay pointer (optional) | -
 
-| tcl | tcl_script | list of scripts
+| ruby | ruby_script | list of scripts | script pointer (optional) | script name (can start or end with "*" as joker) (optional)
 
-| weechat | bar | list of bars
+| tcl | tcl_script | list of scripts | script pointer (optional) | script name (can start or end with "*" as joker) (optional)
 
-| weechat | bar_item | list of bar items
+| weechat | bar | list of bars | bar pointer (optional) | bar name (can start or end with "*" as joker) (optional)
 
-| weechat | bar_window | list of bar windows
+| weechat | bar_item | list of bar items | bar item pointer (optional) | bar item name (can start or end with "*" as joker) (optional)
 
-| weechat | buffer | list of buffers
+| weechat | bar_window | list of bar windows | bar window pointer (optional) | -
 
-| weechat | buffer_lines | lines of a buffer
+| weechat | buffer | list of buffers | buffer pointer (optional) | buffer name (can start or end with "*" as joker) (optional)
 
-| weechat | filter | list of filters
+| weechat | buffer_lines | lines of a buffer | buffer pointer | -
 
-| weechat | history | history of commands
+| weechat | filter | list of filters | - | filter name (can start or end with "*" as joker) (optional)
 
-| weechat | hook | list of hooks
+| weechat | history | history of commands | buffer pointer (if not set, return global history) (optional) | -
 
-| weechat | hotlist | list of buffers in hotlist
+| weechat | hook | list of hooks | - | hook type: command, timer, .. (optional)
 
-| weechat | key | list of key bindings
+| weechat | hotlist | list of buffers in hotlist | - | -
 
-| weechat | nicklist | nicks in nicklist for a buffer
+| weechat | key | list of key bindings | - | -
 
-| weechat | option | list of options
+| weechat | nicklist | nicks in nicklist for a buffer | buffer pointer | nick_xxx or group_xxx to get only nick/group xxx (optional)
 
-| weechat | plugin | list of plugins
+| weechat | option | list of options | - | option name (can start or end with "*" as joker) (optional)
 
-| weechat | window | list of windows
+| weechat | plugin | list of plugins | plugin pointer (optional) | plugin name (can start or end with "*" as joker) (optional)
 
-| xfer | xfer | list of xfer
+| weechat | window | list of windows | window pointer (optional) | window name (can start or end with "*" as joker) (optional)
+
+| xfer | xfer | list of xfer | xfer pointer (optional) | -
 
 |========================================
diff --git a/doc/en/autogen/plugin_api/infos.txt b/doc/en/autogen/plugin_api/infos.txt
index e1b883e2e..32933937c 100644
--- a/doc/en/autogen/plugin_api/infos.txt
+++ b/doc/en/autogen/plugin_api/infos.txt
@@ -1,44 +1,45 @@
-[width="65%",cols="^1,^2,8",options="header"]
+[width="100%",cols="^1,^2,6,6",options="header"]
 |========================================
-| Plugin | Name | Description
-| fifo | fifo_filename | name of FIFO pipe
+| Plugin | Name | Description | Arguments
 
-| irc | irc_buffer | get buffer pointer for an IRC server/channel
+| fifo | fifo_filename | name of FIFO pipe | -
 
-| irc | irc_is_channel | 1 if string is an IRC channel
+| irc | irc_buffer | get buffer pointer for an IRC server/channel/nick | server,channel,nick (channel and nicks are optional)
 
-| irc | irc_nick | get current nick on a server
+| irc | irc_is_channel | 1 if string is an IRC channel | channel name
 
-| irc | irc_nick_color | get nick color
+| irc | irc_nick | get current nick on a server | server name
 
-| irc | irc_nick_from_host | get nick from IRC host
+| irc | irc_nick_color | get nick color | nickname
 
-| weechat | charset_internal | WeeChat internal charset
+| irc | irc_nick_from_host | get nick from IRC host | IRC host (like `:nick!name@server.com`)
 
-| weechat | charset_terminal | terminal charset
+| weechat | charset_internal | WeeChat internal charset | -
 
-| weechat | date | WeeChat compilation date
+| weechat | charset_terminal | terminal charset | -
 
-| weechat | dir_separator | directory separator
+| weechat | date | WeeChat compilation date | -
 
-| weechat | filters_enabled | 1 if filters are enabled
+| weechat | dir_separator | directory separator | -
 
-| weechat | inactivity | keyboard inactivity (seconds)
+| weechat | filters_enabled | 1 if filters are enabled | -
 
-| weechat | version | WeeChat version
+| weechat | inactivity | keyboard inactivity (seconds) | -
 
-| weechat | version_number | WeeChat version (as number)
+| weechat | version | WeeChat version | -
 
-| weechat | weechat_dir | WeeChat directory
+| weechat | version_number | WeeChat version (as number) | -
 
-| weechat | weechat_libdir | WeeChat "lib" directory
+| weechat | weechat_dir | WeeChat directory | -
 
-| weechat | weechat_localedir | WeeChat "locale" directory
+| weechat | weechat_libdir | WeeChat "lib" directory | -
 
-| weechat | weechat_sharedir | WeeChat "share" directory
+| weechat | weechat_localedir | WeeChat "locale" directory | -
 
-| weechat | weechat_site | WeeChat site
+| weechat | weechat_sharedir | WeeChat "share" directory | -
 
-| weechat | weechat_site_download | WeeChat site, download page
+| weechat | weechat_site | WeeChat site | -
+
+| weechat | weechat_site_download | WeeChat site, download page | -
 
 |========================================
diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt
index 9d611550a..df447f3d8 100644
--- a/doc/en/weechat_plugin_api.en.txt
+++ b/doc/en/weechat_plugin_api.en.txt
@@ -4887,7 +4887,7 @@ struct t_hook *weechat_hook_command_run (const char *command,
 
 Arguments:
 
-* 'command': command to hook, may start or end with "*" as joker
+* 'command': command to hook, can start or end with "*" as joker
 * 'callback': function called when command is run, arguments:
 ** 'void *data': pointer
 ** 'struct t_gui_buffer *buffer': buffer where command is executed
@@ -6056,6 +6056,7 @@ Prototype:
 ----------------------------------------
 struct t_hook *weechat_hook_info (const char *info_name,
                                   const char *description,
+                                  const char *args_description,
                                   const char *(*callback)(void *data,
                                                           const char *info_name,
                                                           const char *arguments),
@@ -6066,6 +6067,7 @@ Arguments:
 
 * 'info_name': name of info
 * 'description': description
+* 'args_description': description of arguments (optional, can be NULL)
 * 'callback': function called when info is asked, arguments:
 ** 'void *data': pointer
 ** 'const char *info_name': name of info
@@ -6089,8 +6091,9 @@ my_info_cb (void *data, const char *info_name, const char *arguments)
 
 /* add info "my_info" */
 struct t_hook *my_info_hook = weechat_hook_info ("my_info",
-                                            "Some info",
-                                            &my_info_cb, NULL);
+                                                 "Some info",
+                                                 "Info about arguments",
+                                                 &my_info_cb, NULL);
 ----------------------------------------
 
 Script (Python):
@@ -6098,13 +6101,14 @@ Script (Python):
 [source,python]
 ----------------------------------------
 # prototype
-hook = weechat.hook_info(info_name, description, callback, callback_data)
+hook = weechat.hook_info(info_name, description, args_description, callback, callback_data)
 
 # example
 def my_info_cb(data, info_name, arguments):
     return "some_info"
 
-hook = weechat.hook_info("my_info", "Some info", "my_info_cb", "")
+hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
+                         "my_info_cb", "")
 ----------------------------------------
 
 weechat_hook_infolist
@@ -6118,6 +6122,8 @@ Prototype:
 ----------------------------------------
 struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                       const char *description,
+                                      const char *pointer_description,
+                                      const char *args_description,
                                       const char *(*callback)(void *data,
                                                               const char *infolist_name,
                                                               void *pointer,
@@ -6129,6 +6135,8 @@ Arguments:
 
 * 'infolist_name': name of infolist
 * 'description': description
+* 'pointer_description': description of pointer (optional, can be NULL)
+* 'args_description': description of arguments (optional, can be NULL)
 * 'callback': function called when infolist is asked, arguments:
 ** 'void *data': pointer
 ** 'const char *infolist_name': name of infolist
@@ -6160,6 +6168,8 @@ my_infolist_cb (void *data, const char *infolist_name, void *pointer,
 /* add infolist "my_infolist" */
 struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                     "Infolist with some data",
+                                                    "Info about pointer",
+                                                    "Info about arguments",
                                                     &my_infolist_cb, NULL);
 ----------------------------------------
 
@@ -6168,7 +6178,8 @@ Script (Python):
 [source,python]
 ----------------------------------------
 # prototype
-hook = weechat.hook_infolist(infolist_name, description, callback, callback_data)
+hook = weechat.hook_infolist(infolist_name, description, pointer_description,
+                             args_description, callback, callback_data)
 
 # example
 def my_infolist_cb(data, infolist_name, pointer, arguments):
@@ -6176,7 +6187,9 @@ def my_infolist_cb(data, infolist_name, pointer, arguments):
     # ...
     return my_infolist
 
-hook = weechat.hook_infolist("my_infolist", "Infolist with some data", "my_infolist_cb", "")
+hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
+                             "Info about pointer", "Info about arguments",
+                             "my_infolist_cb", "")
 ----------------------------------------
 
 weechat_unhook
@@ -6800,7 +6813,7 @@ Arguments:
   "-": disable hotlist (global setting, buffer pointer is not used) +
   priority: add buffer to hotlist with this priority
 
-| unread | (N/A) |
+| unread | - |
   set unread marker after last line of buffer
 
 | display | "1", "auto" |
@@ -6853,7 +6866,7 @@ Arguments:
   bind a new key 'xxx', specific to this buffer, value is command to execute
   for this key
 
-| key_unbind_xxx | (N/A) |
+| key_unbind_xxx | - |
   unbind key 'xxx' for this buffer
 
 | input | any string |
@@ -6871,7 +6884,7 @@ Arguments:
   set new value for local variable 'xxx' (variable is created if it does not
   exist)
 
-| localvar_del_xxx | (N/A) |
+| localvar_del_xxx | - |
   remove local variable 'xxx'
 |========================================