changeset 2686:45214e5316cd

Improved description of js_set.
author Yaroslav Zhuravlev <yar@nginx.com>
date Fri, 19 Mar 2021 18:24:34 +0000
parents 5282d6d3d849
children 7ff9d8bda757
files xml/en/docs/http/ngx_http_js_module.xml xml/en/docs/stream/ngx_stream_js_module.xml xml/ru/docs/http/ngx_http_js_module.xml xml/ru/docs/stream/ngx_stream_js_module.xml
diffstat 4 files changed, 72 insertions(+), 8 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_js_module.xml
+++ b/xml/en/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_http_js_module"
         link="/en/docs/http/ngx_http_js_module.html"
         lang="en"
-        rev="26">
+        rev="27">
 
 <section id="summary">
 
@@ -298,11 +298,27 @@ Sets an additional path for njs modules.
 <context>http</context>
 
 <para>
-Sets an njs function for the specified variable.
+Sets an njs <literal>function</literal>
+for the specified <literal>variable</literal>.
 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
 a module function can be referenced.
 </para>
 
+<para>
+The function is called when
+the variable is referenced for the first time for a given request.
+The exact moment depends on a
+<link doc="../dev/development_guide.xml" id="http_phases">phase</link>
+at which the variable is referenced.
+This can be used to perform some logic
+not related to variable evaluation.
+For example, if the variable is referenced only in the
+<link doc="ngx_http_log_module.xml" id="log_format"/> directive,
+its handler will not be executed until the log phase.
+This handler can be used to do some cleanup
+right before the request is freed.
+</para>
+
 </directive>
 
 </section>
--- a/xml/en/docs/stream/ngx_stream_js_module.xml
+++ b/xml/en/docs/stream/ngx_stream_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_stream_js_module"
         link="/en/docs/stream/ngx_stream_js_module.html"
         lang="en"
-        rev="24">
+        rev="25">
 
 <section id="summary">
 
@@ -259,11 +259,27 @@ a module function can be referenced.
 <context>stream</context>
 
 <para>
-Sets an njs function for the specified variable.
+Sets an njs <literal>function</literal>
+for the specified <literal>variable</literal>.
 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
 a module function can be referenced.
 </para>
 
+<para>
+The function is called when
+the variable is referenced for the first time for a given request.
+The exact moment depends on a
+<link doc="stream_processing.xml">phase</link>
+at which the variable is referenced.
+This can be used to perform some logic
+not related to variable evaluation.
+For example, if the variable is referenced only in the
+<link doc="ngx_stream_log_module.xml" id="log_format"/> directive,
+its handler will not be executed until the log phase.
+This handler can be used to do some cleanup
+right before the request is freed.
+</para>
+
 </directive>
 
 </section>
--- a/xml/ru/docs/http/ngx_http_js_module.xml
+++ b/xml/ru/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_http_js_module"
         link="/ru/docs/http/ngx_http_js_module.html"
         lang="ru"
-        rev="26">
+        rev="27">
 
 <section id="summary">
 
@@ -299,11 +299,27 @@ function version(r) {
 <context>http</context>
 
 <para>
-Задаёт функцию njs для указанной переменной.
+Задаёт <literal>функцию</literal> njs
+для указанной <literal>переменной</literal>.
 Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
 можно ссылаться на функцию модуля.
 </para>
 
+<para>
+Функция вызывается в момент
+первого обращения к переменной для данного запроса.
+Точный момент вызова функции зависит от
+<link doc="../dev/development_guide.xml" id="http_phases">фазы</link>,
+в которой происходит обращение к переменной.
+Это можно использовать для реализации дополнительной логики,
+не относящейся к вычислению переменной.
+Например, если переменная указана
+в директиве <link doc="ngx_http_log_module.xml" id="log_format"/>,
+то её обработчик не будет выполняться до фазы записи в лог.
+Этот обработчик также может использоваться для выполнения процедур
+непосредственно перед освобождением запроса.
+</para>
+
 </directive>
 
 </section>
--- a/xml/ru/docs/stream/ngx_stream_js_module.xml
+++ b/xml/ru/docs/stream/ngx_stream_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_stream_js_module"
         link="/ru/docs/stream/ngx_stream_js_module.html"
         lang="ru"
-        rev="24">
+        rev="25">
 
 <section id="summary">
 
@@ -260,11 +260,27 @@ function address(s) {
 <context>stream</context>
 
 <para>
-Задаёт функцию njs для указанной переменной.
+Задаёт <literal>функцию</literal> njs
+для указанной <literal>переменной</literal>.
 Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
 можно ссылаться на функцию модуля.
 </para>
 
+<para>
+Функция вызывается в момент
+первого обращения к переменной для данного запроса.
+Точный момент вызова функции зависит от
+<link doc="stream_processing.xml">фазы</link>,
+в которой происходит обращение к переменной.
+Это можно использовать для реализации дополнительной логики,
+не относящейся к вычислению переменной.
+Например, если переменная указана
+в директиве <link doc="ngx_stream_log_module.xml" id="log_format"/>,
+то её обработчик не будет выполняться до фазы записи в лог.
+Этот обработчик также может использоваться для выполнения процедур
+непосредственно перед освобождением запроса.
+</para>
+
 </directive>
 
 </section>