[LTP] [PATCH v3 3/5] doc: Update library API doc

[Petr Vorel]

about conditional expansion for TST_{SETUP,CLEANUP}.

Reviewed-by: Martin Doucha <mdoucha@suse.cz>
Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
changes v2->v3:
* reword

 doc/library-api-writing-guidelines.txt | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/doc/library-api-writing-guidelines.txt b/doc/library-api-writing-guidelines.txt
index e75c838a1..08468f2fc 100644
--- a/doc/library-api-writing-guidelines.txt
+++ b/doc/library-api-writing-guidelines.txt
@@ -61,3 +61,24 @@ API source code is in 'tst_test.sh', 'tst_security.sh' and 'tst_net.sh'
 
 Changes in the shell API should not introduce uncommon dependencies
 (use basic commands installed everywhere by default).
+
+3.1 Shell libraries
+~~~~~~~~~~~~~~~~~~~
+
+Aside from shell API libraries in 'testcases/lib', it's worth putting
+common code for a group of tests into a shell library. The filename
+should end with '_lib.sh' and the library should load 'tst_test.sh' or
+'tst_net.sh'.
+
+Shell libraries should have conditional expansion for 'TST_SETUP' or 'TST_CLEANUP',
+to avoid surprises when test specific setup/cleanup function is redefined by
+shell library.
+
+[source,sh]
+-------------------------------------------------------------------------------
+# ipsec_lib.sh
+# SPDX-License-Identifier: GPL-2.0-or-later
+TST_SETUP=${TST_SETUP:-ipsec_lib_setup}
+. tst_test.sh
+...
+-------------------------------------------------------------------------------
-- 
2.35.3