[PATCH nft v2 0/1] doc: fix inconsistency in set statement documentation.

[PATCH nft v2 0/1] doc: fix inconsistency in set statement documentation.

[Jeremy Sowden]

The description of the set statement asserts that the set must have been
created with the "dynamic" flag, but the following example doesn't
agree.

The simplest way to resolve the inconsistency would be to add the
missing flag to the example, but the description is not correct and the
example doesn't require the flag, so I've attempted to improve the
description.

Change log:

  * In v1, I was under the impression that the "dynamic" flag was never
    required and just dropped all mention of it from the description.
    However, there are circumstances under which it is required, so in
    v2 I expand the description to explain them.

Jeremy Sowden (1):
  doc: fix inconsisntency in set statement documentation.

 doc/statements.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

-- 
2.24.0

[PATCH nft v2] doc: fix inconsistency in set statement documentation.

[Jeremy Sowden]

The description of the set statement asserts that the set must have been
created with the "dynamic" flag.  However, this is not the case, and it
is contradicted by the following example in which the "dynamic" flag
does not appear.

In fact, one or both of the "dynamic" or the "timeout" flags need to be
used, depending on what the set statement contains.  Amend the
description to explain this more accurately.

Signed-off-by: Jeremy Sowden <jeremy@azazel.net>
---
 doc/statements.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/statements.txt b/doc/statements.txt
index 489bdc299d07..433ee98e3aec 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -669,10 +669,15 @@ SET STATEMENT
 ~~~~~~~~~~~~~
 The set statement is used to dynamically add or update elements in a set from
 the packet path. The set setname must already exist in the given table and must
-have been created with the dynamic flag. Furthermore, these sets must specify
-both a maximum set size (to prevent memory exhaustion) and a timeout (so that
-number of entries in set will not grow indefinitely). The set statement can be
-used to e.g. create dynamic blacklists.
+have been created with one or both of the dynamic and the timeout flags. The
+dynamic flag is required if the set statement expression includes a stateful
+object. The timeout flag is implied if the set is created with a timeout, and is
+required if the set statement updates elements, rather than adding them.
+Furthermore, these sets should specify both a maximum set size (to prevent
+memory exhaustion), and their elements should have a timeout (so their number
+will not grow indefinitely) either from the set definition or from the statement
+that adds or updates them. The set statement can be used to e.g. create dynamic
+blacklists.
 
 [verse]
 {*add* | *update*} *@*'setname' *{* 'expression' [*timeout* 'timeout'] [*comment* 'string'] *}*
-- 
2.24.0

Re: [PATCH nft v2] doc: fix inconsistency in set statement documentation.

[Pablo Neira Ayuso]

On Sat, Nov 30, 2019 at 11:30:57AM +0000, Jeremy Sowden wrote:
> The description of the set statement asserts that the set must have been
> created with the "dynamic" flag.  However, this is not the case, and it
> is contradicted by the following example in which the "dynamic" flag
> does not appear.
> 
> In fact, one or both of the "dynamic" or the "timeout" flags need to be
> used, depending on what the set statement contains.  Amend the
> description to explain this more accurately.

Applied, thanks.