More better docs

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.

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