From 19f495a9a4cb04d2c16a1b8b33dbcdf01f952947 Mon Sep 17 00:00:00 2001
From: Yu-Jie Lin <livibetter@gmail.com>
Date: Sat, 21 Sep 2013 05:46:54 +0800
Subject: add doc for skipped HTML comments

---
 docs/usage.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

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
 =================
 
-- 
cgit v1.2.1