From 67f7079c1a43cce1d18c07db831a342096393a33 Mon Sep 17 00:00:00 2001
From: Brown <github@muglug.com>
Date: Fri, 19 Jun 2020 11:57:34 -0400
Subject: [PATCH] More better docs

---
 .../avoiding_false_positives.md               | 22 +++++++++++++++++++
 docs/security_analysis/custom_taint_sinks.md  | 10 +++++++--
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/docs/security_analysis/avoiding_false_positives.md b/docs/security_analysis/avoiding_false_positives.md
index 44dae8500..af6890986 100644
--- a/docs/security_analysis/avoiding_false_positives.md
+++ b/docs/security_analysis/avoiding_false_positives.md
@@ -6,6 +6,28 @@ Nobody likes false-positives!
 
 There are a number of ways you can prevent them:
 
+## Removing taints
+
+Some operations remove taints from data.
+
+For example, wrapping `$_GET['name']` in an `htmlentities` call prevents cross-site-scripting attacks.
+
+Psalm allows you to remove taints via an annotation:
+
+```php
+<?php // trackTaints
+
+function echoVar(string $str) : void {
+    /**
+     * @psalm-taint-remove html
+     */
+    $str = preg_replace('/[^a-z]/', '', $str);
+    echo $str;
+}
+
+echoVar($_GET["text"]);
+```
+
 ## Specializing taints in functions
 
 For functions, methods and classes you can use the `@psalm-taint-specialize` annotation.
diff --git a/docs/security_analysis/custom_taint_sinks.md b/docs/security_analysis/custom_taint_sinks.md
index c4c05cfa3..a5a60636f 100644
--- a/docs/security_analysis/custom_taint_sinks.md
+++ b/docs/security_analysis/custom_taint_sinks.md
@@ -4,7 +4,13 @@ You can define your own taint sinks two ways
 
 ## Using a docblock annotation
 
-`@psalm-taint-sink`
+The `@psalm-taint-sink <taint-type> <param-name>` annotation allows you to define a taint sink.
+
+Any tainted value matching the given [taint type](index.md#taint-types) will be reported as an error by Psalm.
+
+### Example
+
+Here the `PDOWrapper` class has an `exec` method that should not recieve tainted SQL, so we can prevent its insertion:
 
 ```php
 <?php
@@ -19,5 +25,5 @@ class PDOWrapper {
 
 ## Using a Psalm plugin
 
-or with a plugin
+TODO