[Tarantool-patches] [PATCH 0/2] module_api: followup changes for merger part

[Tarantool-patches] [PATCH 0/2] module_api: followup changes for merger part

[Timur Safin]

There were few complains about comments in the patchset sent
for issue #5384:
- we have been asked to extend reasonably ibuf.h documentation, making 
  it more self-contained;
- and to fix module_api test comments, making them more doxygen

P.S.
Actualy I don't know whether we really want it be committed to the 
2.6 we plan to release soon. But looks like commenting changes 
in the external API might still be a good idea. You decide.

Timur Safin (2):
  module api: proper documentation for the ibuf wrapper
  module api: polish module_api test

 src/box/ibuf.h            | 33 ++++++++++++++++++++++++++++++---
 test/app-tap/module_api.c |  8 ++++----
 2 files changed, 34 insertions(+), 7 deletions(-)

-- 
2.20.1

[Tarantool-patches] [PATCH 1/2] module api: proper documentation for the ibuf wrapper

[Timur Safin]

We have extended module api as part of #5384 but there were
some complains that this part ofapi is not self-contained
and it's impossible to understand what's going on there
without looking into small/ibuf.[hc] sources.

Now we try to document the essential part of ibuf structure
so API should makes much more sense now.

Follow-up to #5384
---
 src/box/ibuf.h | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/src/box/ibuf.h b/src/box/ibuf.h
index 8c6d053c4..f411a13c9 100644
--- a/src/box/ibuf.h
+++ b/src/box/ibuf.h
@@ -40,19 +40,42 @@ extern "C" {
 
 /** \cond public */
 
+/**
+ * "@p box_ibuf_t is an opaque alias for struct @p ibuf
+ * defined in the small library.
+ *
+ * The structure is a buffer composing of several pointers and
+ * counters, which serve purpose of keeping 2 joint areas
+ * in buffer:
+ * - useful area [rpos, wpos)
+ * - and one, which is unused yet [wpos, end)
+ *
+ *        +---+--------+---------+
+ * buf -> |   |..used..|.unused..|
+ *        +---+--------+---------+
+ *            ^        ^         ^
+ *            rpos     wpos      end
+ *
+ */
 typedef struct ibuf box_ibuf_t;
 
 /**
- * Reserve requested amount of bytes in ibuf buffer
+ * Reserve requested amount of bytes in ibuf buffer.
+ *
  * @param ibuf buffer used for allocation
  * @param size allocated bytes
+ *
  * @retval NULL on error, check diag.
  */
 API_EXPORT void *
 box_ibuf_reserve(box_ibuf_t *ibuf, size_t size);
 
 /**
- * Return pointers to read range pointers used [rpos..wpos)
+ * Return pointers to read range pointers used [rpos..wpos).
+ *
+ * All arguments should be non-NULL, with exception of last one
+ * @p wpos which is optional and allows NULL.
+ *
  * @param ibuf ibuf structure
  * @param rpos where to place ibuf.rpos address
  * @param wpos where to place ibuf.wpos address
@@ -61,7 +84,11 @@ API_EXPORT void
 box_ibuf_read_range(box_ibuf_t *ibuf, char ***rpos, char ***wpos);
 
 /**
- * Return pointers to write range pointers used [wpos..end)
+ * Return pointers to write range pointers used [wpos..end).
+ *
+ * All arguments should be non-NULL, with exception of last one
+ * @p end which is optional and allows NULL.
+ *
  * @param ibuf ibuf structure
  * @param wpos where to place ibuf.rpos address
  * @param end where to place ibuf.wpos address
-- 
2.20.1

[Tarantool-patches] [PATCH 2/2] module api: polish module_api test

[Timur Safin]

Use proper doxygen blocks in module_api test

Follow-up to #5348
---
 test/app-tap/module_api.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/test/app-tap/module_api.c b/test/app-tap/module_api.c
index ce7fa2353..0feae0b9b 100644
--- a/test/app-tap/module_api.c
+++ b/test/app-tap/module_api.c
@@ -2287,9 +2287,9 @@ test_tuple_new(struct lua_State *L)
 
 /* }}} test_tuple_new */
 
-/*
+/**
  * Check that argument is a tuple of any format, without
- * its verification
+ * its verification.
  */
 static int
 test_tuple_validate_default(lua_State *L)
@@ -2306,8 +2306,8 @@ test_tuple_validate_default(lua_State *L)
 	return 1;
 }
 
-/*
- * Validate tuple with format of single boolean field
+/**
+ * Validate tuple with format of single boolean field.
  */
 static int
 test_tuple_validate_formatted(lua_State *L)
-- 
2.20.1

Re: [Tarantool-patches] [PATCH 0/2] module_api: followup changes for merger part

[Vladislav Shpilevoy]

Hi! I don't see a branch name. And can't find anything by '5384' in
name.

On 22.10.2020 12:20, Timur Safin wrote:
> There were few complains about comments in the patchset sent
> for issue #5384:
> - we have been asked to extend reasonably ibuf.h documentation, making 
>   it more self-contained;
> - and to fix module_api test comments, making them more doxygen
> 
> P.S.
> Actualy I don't know whether we really want it be committed to the 
> 2.6 we plan to release soon. But looks like commenting changes 
> in the external API might still be a good idea. You decide.
> 
> Timur Safin (2):
>   module api: proper documentation for the ibuf wrapper
>   module api: polish module_api test
> 
>  src/box/ibuf.h            | 33 ++++++++++++++++++++++++++++++---
>  test/app-tap/module_api.c |  8 ++++----
>  2 files changed, 34 insertions(+), 7 deletions(-)
> 

Re: [Tarantool-patches] [PATCH 2/2] module api: polish module_api test

[Alexander Turenko]

On Thu, Oct 22, 2020 at 01:20:41PM +0300, Timur Safin wrote:
> Use proper doxygen blocks in module_api test
> 
> Follow-up to #5348

#5384.

Re: [Tarantool-patches] [PATCH 0/2] module_api: followup changes for merger part

[Alexander Turenko]

I have no objections.