add doc for skipped HTML comments

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/usage.rst b/docs/usage.rst
index 560cdf0..954edd2 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -44,6 +44,9 @@ To use these attributes, simply using bitwise *OR* operator, that is ``A | B``:
 Skipped HTML elements
 =====================
 
+Elements
+--------
+
 By default, there are a few HTML elements that :func:`smartypants.smartypants`
 do not try to be smart with them:
 
@@ -68,6 +71,28 @@ being used by :func:`smartypants.smartypants`. You could actually overwrite
 expression.
 
 
+Comments
+--------
+
+HTML comments are always skipped since they are not rendered in browsers.
+
+.. code:: python
+
+  >>> from smartypants import smartypants as sp
+  >>> print(sp('<!-- <span>"foobar"</span> -->'))
+  <!-- <span>"foobar"</span> -->
+
+.. important::
+  
+  Beware of ``--``, which should not or must not be in a HTML comment.
+
+  .. code:: python
+
+    >>> from smartypants import smartypants as sp
+    >>> print(sp('<!-- <span>"foo--bar"</span> -->'))
+    <!&#8212; <span>&#8221;foo&#8212;bar&#8221;</span> &#8212;>
+
+
 Backslash escapes
 =================