From adc98575ff06bd7e0d45e318fbed3d0ef0ca53ff Mon Sep 17 00:00:00 2001
From: Vladislav Shpilevoy <v.shpilevoy@tarantool.org>
Date: Sat, 15 Feb 2020 18:58:21 +0100
Subject: [PATCH] tuple: document all missed box.tuple.* methods

In #4684 it was found that box.tuple.* contained some private
functions: bless(), encode(), and is().

Bless() and encode() didn't make any sense for a user, so they
were hidden into box.internal.tuple.*.

But box.tuple.is() is actually a useful thing. It is harnessed in
the tests a lot, and is likely to be already used by customers,
because it is available in box.tuple.* for a long time. It is a
matter of time when someone will open a doc ticket saying that
box.tuple.is() is not documented. The patch makes it legally
public.

Follow-up #4684

@TarantoolBot document
Title: box.tuple.is()
```Lua
box.tuple.is(object)
```
A function to check whether a given object is a tuple cdata
object. Returns true or false. Never raises nor returns an error.
---
 src/box/lua/tuple.lua   |  7 ++++---
 test/box/tuple.result   | 40 ++++++++++++++++++++++++++++++++++++++++
 test/box/tuple.test.lua | 14 ++++++++++++++
 3 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/src/box/lua/tuple.lua b/src/box/lua/tuple.lua
index eb3946a0f5..f97aa15796 100644
--- a/src/box/lua/tuple.lua
+++ b/src/box/lua/tuple.lua
@@ -352,7 +352,8 @@ internal.tuple.tostring = nil
 internal.tuple.bless = tuple_bless
 internal.tuple.encode = tuple_encode
 
--- The function is internal in a sense that it is not documented.
--- But it is safe and widely used in the tests. Keep it here at
--- least for test code.
+-- Public API, additional to implemented in C.
+
+-- is() is implemented in Lua, because then it is
+-- easy to be JITed.
 box.tuple.is = is_tuple
diff --git a/test/box/tuple.result b/test/box/tuple.result
index 78f919deba..a499aa43ad 100644
--- a/test/box/tuple.result
+++ b/test/box/tuple.result
@@ -1450,6 +1450,46 @@ level == max_depth + 5 or {level, max_depth}
 ---
 - true
 ...
+-- gh-4684: some box.tuple.* methods were private and could be
+-- used by customers to shoot in their own legs. Some of them
+-- were moved to a more secret place. box.tuple.is() was moved to
+-- the public API, legally.
+box.tuple.is()
+---
+- false
+...
+box.tuple.is(nil)
+---
+- false
+...
+box.tuple.is(box.NULL)
+---
+- false
+...
+box.tuple.is({})
+---
+- false
+...
+box.tuple.is(ffi.new('char[1]'))
+---
+- false
+...
+box.tuple.is(1)
+---
+- false
+...
+box.tuple.is('1')
+---
+- false
+...
+box.tuple.is(box.tuple.new())
+---
+- true
+...
+box.tuple.is(box.tuple.new({1}))
+---
+- true
+...
 msgpack.cfg({encode_max_depth = max_depth, encode_deep_as_nil = deep_as_nil})
 ---
 ...
diff --git a/test/box/tuple.test.lua b/test/box/tuple.test.lua
index baf2f22d5b..b83fca5cdf 100644
--- a/test/box/tuple.test.lua
+++ b/test/box/tuple.test.lua
@@ -496,4 +496,18 @@ while tuple ~= nil do level = level + 1 tuple = tuple[1] end
 -- serializer allows deeper tables.
 level == max_depth + 5 or {level, max_depth}
 
+-- gh-4684: some box.tuple.* methods were private and could be
+-- used by customers to shoot in their own legs. Some of them
+-- were moved to a more secret place. box.tuple.is() was moved to
+-- the public API, legally.
+box.tuple.is()
+box.tuple.is(nil)
+box.tuple.is(box.NULL)
+box.tuple.is({})
+box.tuple.is(ffi.new('char[1]'))
+box.tuple.is(1)
+box.tuple.is('1')
+box.tuple.is(box.tuple.new())
+box.tuple.is(box.tuple.new({1}))
+
 msgpack.cfg({encode_max_depth = max_depth, encode_deep_as_nil = deep_as_nil})
-- 
GitLab