[5pt] Revise triggers documentation

[TarantoolBot]

Revise triggers documentation

Update: new triggers module tarantool/tarantool#8622

Product: Tarantool
Audience/target: developers
Root document: https://www.tarantool.io/en/doc/latest/book/box/triggers/
SME: @ Totktonada

Details

The Triggers chapter of the doc begins with a list associated with trigger functions. The descriptions of some of those functions contain the following phrases:

"If the parameters are (nil, old-trigger-function), then the old trigger is deleted.
If both parameters are omitted, then the response is a list of existing trigger functions.
Details about trigger characteristics are in the triggers section."

Looks like the trigger documentation has to be revised. Focus on adding, deleting, and replacing trigger functions, not on the parameters. Users want to know how to perform specific actions and don't tend to search for parameters.

Consider describing how to add/delete/replace trigger functions on the Triggers page. In this case, remove the parameter-focused wordings from the function descriptions, unless they are absolutely necessary.

Below is a list of affected pages, coming from the main Triggers page:

https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/on_connect/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/on_disconnect/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/on_auth/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/on_replace/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/before_replace/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_txn_management/on_commit/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_ctl/on_schema_init/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_ctl/on_shutdown/
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/on_access_denied/

https://www.tarantool.io/en/doc/latest/reference/reference_lua/net_box/#net-box-on-connect (note)
https://www.tarantool.io/en/doc/latest/reference/reference_lua/net_box/#net-box-on-disconnect (note)
https://www.tarantool.io/en/doc/latest/reference/reference_lua/net_box/#net-box-on-schema-reload (note)

https://www.tarantool.io/en/doc/latest/reference/reference_lua/swim/#swim-on-member-event---there is no description of adding/revising/deleting the trigger function whatsoever

---

<…>ger function which
will be replaced by
trigger-function

Return:|nil or function pointer|

If the parameters are (nil, old-trigger-function), then the ol<…>

https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/on_replace/

The return value description is incomplete.

There are three cases: adding, replacing and deleting the trigger function.

• When added: whether it returns nil or the new function?
• When replaced: whether it returns old or new function?
• When deleted: returns the old function, correct?

BTW, what 'function pointer' means in context of Lua? Just function?

How about restructurize the doc from 'if parameters are <...>, the function does <...>' to 'to make <...>, call <...>' (I mean 'to add', 'to replace', 'to delete'). It would be much easier to use the doc in practice. If we'll do, do this for all trigger API references.

[Totktonada]

(It was me.)

See, I restructurized the existing API description this way here just because it is easier to explain things this way.

[xuniq]

Connected with #1690

[patiencedaur]

More connected issues: #1967, #2377