doc: add note about things not allowed in callback of function hook_completion (plugin API reference)

3 files changed, 29 insertions, 0 deletions

diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt
index 89ecc989b..bce66cc4b 100644
--- a/doc/en/weechat_plugin_api.en.txt
+++ b/doc/en/weechat_plugin_api.en.txt
@@ -8637,6 +8637,15 @@ Completion names are global (shared across WeeChat and plugins). So it is
 recommended to choose a name with a unique prefix, like "plugin_xxx" (where
 "xxx" is your item name).
 
+[IMPORTANT]
+The callback must only call function
+<<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>
+and must *NOT* update the command line. +
+To update the command line when key[Tab] is pressed, you can use the function
+<<_weechat_hook_command_run,weechat_hook_command_run>> with command:
+"/input complete_next" (and you must return 'WEECHAT_RC_OK_EAT' if your callback
+has updated the command line, so that WeeChat will not perform the completion).
+
 Return value:
 
 * pointer to new hook, NULL if error occurred
diff --git a/doc/fr/weechat_plugin_api.fr.txt b/doc/fr/weechat_plugin_api.fr.txt
index 2964af642..1fa1233b0 100644
--- a/doc/fr/weechat_plugin_api.fr.txt
+++ b/doc/fr/weechat_plugin_api.fr.txt
@@ -8778,6 +8778,16 @@ Les noms de complétion sont globaux (partagés entre WeeChat et les extensions)
 Il est donc recommandé de choisir un nom avec un préfixe unique, comme
 "monextension_xxx" (où "xxx" est le nom de votre complétion).
 
+[IMPORTANT]
+Le "callback" doit seulement appeler la fonction
+<<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>
+et ne doit *PAS* mettre à jour la ligne de commande. +
+Pour mettre à jour la ligne de commande quand key[Tab] est pressé, vous pouvez
+utiliser la fonction <<_weechat_hook_command_run,weechat_hook_command_run>>
+avec la commande : "/input complete_next" (et vous devez retourner
+'WEECHAT_RC_OK_EAT' si votre "callback" a mis à jour la ligne de commande, de
+sorte que WeeChat n'exécute pas la complétion).
+
 Valeur de retour :
 
 * pointeur vers le nouveau "hook", NULL en cas d'erreur
diff --git a/doc/it/weechat_plugin_api.it.txt b/doc/it/weechat_plugin_api.it.txt
index 9a7d8800f..23d90ac9f 100644
--- a/doc/it/weechat_plugin_api.it.txt
+++ b/doc/it/weechat_plugin_api.it.txt
@@ -8769,6 +8769,16 @@ I nomi del completamento sono globali (condivisi tra WeeChat e plugin). Si
 raccomanda pertanto di scegliere un nome con un prefisso unico, come
 "plugin_xxx" (dove "xxx" è il nome del proprio elemento).
 
+// TRANSLATION MISSING
+[IMPORTANT]
+The callback must only call function
+<<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>
+and must *NOT* update the command line. +
+To update the command line when key[Tab] is pressed, you can use the function
+<<_weechat_hook_command_run,weechat_hook_command_run>> with command:
+"/input complete_next" (and you must return 'WEECHAT_RC_OK_EAT' if your callback
+has updated the command line, so that WeeChat will not perform the completion).
+
 Valore restituito:
 
 * puntatore al nuovo hook, NULL in caso di errore