[5pt] Revise triggers documentation

Revise triggers documentation

Update: new triggers module https://github.com/tarantool/tarantool/pull/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.

Start with the Triggers chapter and the affected Lua API reference pages listed in the issue, especially box_space/on_replace and swim on-member-event. Review the new triggers module from pull request 8622 and clarify return-value behavior with the listed SME. Done means the documentation explains adding, replacing, and deleting trigger functions consistently, with parameter-focused wording removed where unnecessary.