From d2033c80358b9279f9cce4c5fd90bf3babab0a10 Mon Sep 17 00:00:00 2001
From: mariopil <112880809+mariopil@users.noreply.github.com>
Date: Mon, 9 Jan 2023 13:43:32 +0100
Subject: [PATCH] Hooks docs update (#279)

* Added hooks-guard-call-non-const checker doc, updated hooks-guard-in-for doc.
---
 xrpl-hooks-docs/docs.ts                       |  2 ++
 .../md/hooks-guard-call-non-const.md          |  6 ++++
 xrpl-hooks-docs/md/hooks-guard-in-for.md      | 33 +++++++++++++++----
 3 files changed, 35 insertions(+), 6 deletions(-)
 create mode 100644 xrpl-hooks-docs/md/hooks-guard-call-non-const.md

diff --git a/xrpl-hooks-docs/docs.ts b/xrpl-hooks-docs/docs.ts
index ce8bde4..bde8314 100644
--- a/xrpl-hooks-docs/docs.ts
+++ b/xrpl-hooks-docs/docs.ts
@@ -22,6 +22,7 @@ import hooksFloatManipPure from './md/hooks-float-manip-pure.md'
 import hooksFloatOnePure from './md/hooks-float-one-pure.md'
 import hooksFloatPure from './md/hooks-float-pure.md'
 import hooksGuardCalled from './md/hooks-guard-called.md'
+import hooksGuardCallNonConst from './md/hooks-guard-call-non-const.md'
 import hooksGuardInFor from './md/hooks-guard-in-for.md'
 import hooksGuardInWhile from './md/hooks-guard-in-while.md'
 import hooksHashBufLen from './md/hooks-hash-buf-len.md'
@@ -70,6 +71,7 @@ const docs: { [key: string]: string } = {
   'hooks-float-one-pure': hooksFloatOnePure,
   'hooks-float-pure': hooksFloatPure,
   'hooks-guard-called': hooksGuardCalled,
+  'hooks-guard-call-non-const': hooksGuardCallNonConst,
   'hooks-guard-in-for': hooksGuardInFor,
   'hooks-guard-in-while': hooksGuardInWhile,
   'hooks-hash-buf-len': hooksHashBufLen,
diff --git a/xrpl-hooks-docs/md/hooks-guard-call-non-const.md b/xrpl-hooks-docs/md/hooks-guard-call-non-const.md
new file mode 100644
index 0000000..875842f
--- /dev/null
+++ b/xrpl-hooks-docs/md/hooks-guard-call-non-const.md
@@ -0,0 +1,6 @@
+# hooks-guard-call-non-const
+
+Only compile-time constants can be used as an argument in loop GUARD call. This check warns if a non compile-time constant is used. 
+It also checks whether a compile-time constant is used as a first argument of `_g()` call and whether it is a unique value. If not - it warns.
+
+[Read more](https://xrpl-hooks.readme.io/v2.0/docs/loops-and-guarding)
diff --git a/xrpl-hooks-docs/md/hooks-guard-in-for.md b/xrpl-hooks-docs/md/hooks-guard-in-for.md
index ae0c0d4..9240108 100644
--- a/xrpl-hooks-docs/md/hooks-guard-in-for.md
+++ b/xrpl-hooks-docs/md/hooks-guard-in-for.md
@@ -1,14 +1,35 @@
 # hooks-guard-in-for
 
-A guard is a marker that must be placed in your code at the top of each loop. Consider the following for-loop in C:
+Consider the following for-loop in C:
 
 ```c
-  #define GUARD(maxiter) _g(__LINE__, (maxiter)+1)
-
-  for (int i = 0; GUARD(3), i < 3; ++i)
+#define GUARD(maxiter) _g(__LINE__, (maxiter)+1)
+for (int i = 0; GUARD(3), i < 3; ++i)
 ```
 
-<BR/>
-This is the only way to satisfy the guard rule when using a for-loop in C.
+To satisfy the guard rule when using a for-loop in C guard should be 
+placed either in the condition part of the loop, or as a first call in loop body, e.g.
+
+```c
+for(int i = 0; i < 3; ++i) {
+  GUARD(3);
+}
+```
+
+In case of nested loops, the guard limit value should be 
+multiplied by a number of iterations in each loop, e.g.
+
+```c
+for(int i = 0; GUARD(3), i < 3; ++i) {
+  for (int j = 0; GUARD(17), j < 5; ++j)
+}
+```
+
+```
+(most descendant loop iterations + 1) * (each parent loops iterations) - 1
+```
+
+This check will warn if the GUARD call is missing and also it will propose a GUARD value based on the for loop initial value,
+the increment and loop condition.
 
 [Read more](https://xrpl-hooks.readme.io/v2.0/docs/loops-and-guarding)