Improve documentation

README.md

@@ -14,17 +14,52 @@ pip install nh3
 
 ## Usage
 
-```python
-import nh3
+`nh3` exposes these functions and attributes.
+For full documentation including parameters, check their docstrings or [the source](https://github.com/messense/nh3/blob/main/src/lib.rs).
 
-print(nh3.clean("<b><img src=\"\">I'm not trying to XSS you</b>"))
+### `clean()`
+
+Sanitize an HTML fragment according to the given options.
+
+```pycon
+>>> nh3.clean("<b><img src='' onerror='alert(\\'hax\\')'>I'm not trying to XSS you</b>")
+'<b><img src="">I\'m not trying to XSS you</b>'
+```
+
+### `clean_text()`
+
+Turn an arbitrary string into unformatted HTML.
+
+```pycon
+>>> nh3.clean_text("<3")
+'&lt;3'
+```
+
+### `is_html()`
+
+Determine if a given string contains HTML.
+
+```pycon
+>>> nh3.is_html("Hello")
+False
+>>> nh3.is_html("Hello <b>World</b>")
+True
 ```
 
+### `ALLOWED_TAGS`
+
+The default set of tags allowed by `clean()`.
+
+### `ALLOWED_ATTRIBUTES`
+
+The default mapping of tags to allowed attributes for `clean()`.
+
 ## Performance
 
-Running on MacBook Air (M2, 2022)
+A quick benchmark showing that nh3 is about 20 times faster than the deprecated [bleach](https://pypi.org/project/bleach/) package.
+Measured on a MacBook Air (M2, 2022).
 
-```python
+```ipython
 Python 3.11.0 (main, Oct 25 2022, 16:25:24) [Clang 14.0.0 (clang-1400.0.29.102)]
 Type 'copyright', 'credits' or 'license' for more information
 IPython 8.9.0 -- An enhanced Interactive Python. Type '?' for help.

src/lib.rs

@@ -5,7 +5,7 @@ use pyo3::exceptions::PyTypeError;
 use pyo3::prelude::*;
 use pyo3::types::{PyString, PyTuple};
 
-/// Sanitizes an HTML fragment in a string according to the configured options.
+/// Sanitize an HTML fragment according to the given options.
 ///
 /// :param html: Input HTML fragment
 /// :type html: ``str``
@@ -172,7 +172,7 @@ fn clean(
     Ok(cleaned)
 }
 
-/// Turn an arbitrary string into unformatted HTML
+/// Turn an arbitrary string into unformatted HTML.
 ///
 /// This function is roughly equivalent to PHP’s htmlspecialchars and htmlentities.
 /// It is as strict as possible, encoding every character that has special meaning to the HTML parser.
@@ -186,11 +186,11 @@ fn clean_text(py: Python, html: &str) -> String {
     py.allow_threads(|| ammonia::clean_text(html))
 }
 
-/// Determine if a given string contains HTML
+/// Determine if a given string contains HTML.
 ///
-/// This function is parses the full string into HTML and checks if the input contained any HTML syntax.
+/// This function parses the full string and checks for any HTML syntax.
 ///
-/// Note: This function will return positively for strings that contain invalid HTML syntax
+/// Note: This function will return True for strings that contain invalid HTML syntax
 /// like ``<g>`` and even ``Vec::<u8>::new()``.
 ///
 /// :param html: Input string