From 7367b212ae22d3882ff30ae54d464f3159879886 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= <daniel.marjamaki@gmail.com>
Date: Sun, 25 Aug 2019 16:16:20 +0200
Subject: [PATCH] Manual: Add chapter about safe checks

---
 man/manual.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/man/manual.md b/man/manual.md
index 2c43597af..510e6966e 100644
--- a/man/manual.md
+++ b/man/manual.md
@@ -595,6 +595,61 @@ Newline
 
 Carriage return
 
+# Safe checking
+
+This is pedantic checking. It can warn even if your code works perfectly.
+
+Basically:
+
+ * A function is "safe" if it can't crash.
+ * A class is "safe" if it can't crash.
+
+As an example, this function is not "safe":
+
+    int dostuff(int x)
+    {
+        int a[] = {1, 2, 3, 4};
+        return a[x];
+    }
+
+This code might work perfectly, if the value of `x` is always 0-3.
+
+But it is not "safe". If the value of `x` would be negative or greater than 4, then it could crash.
+
+Important: If Cppcheck complains that your function is not "safe" then this does not mean there is a real bug.
+
+## Activate "safe" checks
+
+The "safe" checks can be activated in the Cppcheck-GUI in the project settings.
+
+## Annotations
+
+With annotations you can limit the safety checks.
+
+Using MS SAL:
+
+    int dostuff(_In_range_(0,3) int x)
+    {
+        int a[] = {1, 2, 3, 4};
+        return a[x];
+    }
+
+Using Cppcheck annotations:
+
+    int dostuff(__cppcheck_low__(0) __cppcheck_high__(3) int x)
+    {
+        int a[] = {1, 2, 3, 4};
+        return a[x];
+    }
+
+Using C++ code contracts:
+
+    int dostuff(int x) [[expects: x >= 0 && x <= 3]]
+    {
+        int a[] = {1, 2, 3, 4};
+        return a[x];
+    }
+
 # Addons
 
 Addons are scripts with extra checks. Cppcheck is distributed with a few addons.