doc/api: add priority in function config_new (issue #1872)

4 files changed, 73 insertions, 24 deletions

diff --git a/doc/en/includes/autogen_api_config_priority.en.adoc b/doc/en/includes/autogen_api_config_priority.en.adoc
new file mode 100644
index 000000000..e46bb99f5
--- /dev/null
+++ b/doc/en/includes/autogen_api_config_priority.en.adoc
@@ -0,0 +1,36 @@
+//
+// This file is auto-generated by script docgen.py.
+// DO NOT EDIT BY HAND!
+//
+
+// tag::config_priority[]
+[width="30%",cols="1,3,2",options="header"]
+|===
+| Rank | File | Priority
+| 1 | sec.conf | 120000
+| 2 | weechat.conf | 110000
+| 3 | plugins.conf | 100000
+| 4 | charset.conf | 16000
+| 5 | logger.conf | 15000
+| 6 | exec.conf | 14000
+| 7 | trigger.conf | 13000
+| 8 | spell.conf | 12000
+| 9 | alias.conf | 11000
+| 10 | buflist.conf | 10000
+| 11 | fifo.conf | 9000
+| 12 | typing.conf | 8000
+| 13 | xfer.conf | 7000
+| 14 | irc.conf | 6000
+| 15 | relay.conf | 5000
+| 16 | guile.conf | 4070
+| 17 | javascript.conf | 4060
+| 18 | lua.conf | 4050
+| 19 | perl.conf | 4040
+| 20 | php.conf | 4030
+| 21 | python.conf | 4020
+| 22 | ruby.conf | 4010
+| 23 | tcl.conf | 4000
+| 24 | script.conf | 3000
+| 25 | fset.conf | 2000
+|===
+// end::config_priority[]
diff --git a/doc/en/includes/autogen_api_hdata.en.adoc b/doc/en/includes/autogen_api_hdata.en.adoc
index 1e2ca8f76..ccfda5f8f 100644
--- a/doc/en/includes/autogen_api_hdata.en.adoc
+++ b/doc/en/includes/autogen_api_hdata.en.adoc
@@ -707,6 +707,7 @@ _count_   (integer) +
 _last_config_file_ +
 
 | _plugin_   (pointer, hdata: "plugin") +
+_priority_   (integer) +
 _name_   (string) +
 _filename_   (string) +
 _file_   (pointer) +
diff --git a/doc/en/includes/autogen_api_plugins_priority.en.adoc b/doc/en/includes/autogen_api_plugins_priority.en.adoc
index 472c3d1c0..8a24ab563 100644
--- a/doc/en/includes/autogen_api_plugins_priority.en.adoc
+++ b/doc/en/includes/autogen_api_plugins_priority.en.adoc
@@ -4,26 +4,30 @@
 //
 
 // tag::plugins_priority[]
-. charset (16000)
-. logger (15000)
-. exec (14000)
-. trigger (13000)
-. spell (12000)
-. alias (11000)
-. buflist (10000)
-. fifo (9000)
-. typing (8000)
-. xfer (7000)
-. irc (6000)
-. relay (5000)
-. guile (4070)
-. javascript (4060)
-. lua (4050)
-. perl (4040)
-. php (4030)
-. python (4020)
-. ruby (4010)
-. tcl (4000)
-. script (3000)
-. fset (2000)
+[width="30%",cols="1,3,2",options="header"]
+|===
+| Rank | Plugin | Priority
+| 1 | charset | 16000
+| 2 | logger | 15000
+| 3 | exec | 14000
+| 4 | trigger | 13000
+| 5 | spell | 12000
+| 6 | alias | 11000
+| 7 | buflist | 10000
+| 8 | fifo | 9000
+| 9 | typing | 8000
+| 10 | xfer | 7000
+| 11 | irc | 6000
+| 12 | relay | 5000
+| 13 | guile | 4070
+| 14 | javascript | 4060
+| 15 | lua | 4050
+| 16 | perl | 4040
+| 17 | php | 4030
+| 18 | python | 4020
+| 19 | ruby | 4010
+| 20 | tcl | 4000
+| 21 | script | 3000
+| 22 | fset | 2000
+|===
 // end::plugins_priority[]
diff --git a/doc/en/weechat_plugin_api.en.adoc b/doc/en/weechat_plugin_api.en.adoc
index 95d00a573..d8c23f836 100644
--- a/doc/en/weechat_plugin_api.en.adoc
+++ b/doc/en/weechat_plugin_api.en.adoc
@@ -6263,7 +6263,7 @@ Functions for configuration files.
 
 ==== config_new
 
-_Updated in 1.5._
+_Updated in 1.5, 3.9._
 
 Create a new configuration file.
 
@@ -6281,7 +6281,11 @@ struct t_config_file *weechat_config_new (const char *name,
 
 Arguments:
 
-* _name_: name of configuration file (without path or extension)
+* _name_: name of configuration file (without path or extension); a priority
+  is allowed before the name, with format `nnn|name` where `nnn` is non-negative
+  integer with priority; default priority is 1000; files are sorted by priority
+  from higher to lower when running command `/reload`
+  (see priority of configuration files below)
 * _callback_reload_: function called when configuration file is reloaded with
   `/reload` (optional, can be NULL, see below), arguments and return value:
 ** _const void *pointer_: pointer
@@ -6317,6 +6321,10 @@ You should call this function only after adding some sections (with
 <<_config_new_section,config_new_section>>) and options (with
 <<_config_new_option,config_new_option>>).
 
+Priority of default configuration files:
+
+include::includes/autogen_api_config_priority.en.adoc[tag=config_priority]
+
 C example:
 
 [source,c]