Clean up a bunch of code and comments.

[dead/halcyon.git] / src / Html.hs

diff --git a/src/Html.hs b/src/Html.hs
index 59876a5b5c0e9fd9f782442a7e5232dee4679ca6..3abd82b037879becf76d8f22bab2c45de50ddd3f 100644 (file)
--- a/src/Html.hs
+++ b/src/Html.hs
@@ -7,6 +7,34 @@ import Test.Tasty ( TestTree, testGroup )
 import Test.Tasty.HUnit ( (@?=), testCase )
 import Text.HTML.TagSoup.Entity ( lookupEntity )
 
+
+-- | Replace (x)html entities in a 'String'. To do this, we search
+--   through the string looking for ampersands which may indicate the
+--   beginning of an entity.
+--
+--   If we find one and there's a semicolon after it, we attempt to
+--   look up the identifier that we found between the ampersand and
+--   the semicolon. If an entity is found, we replace the ampersand,
+--   semicolon, and everything in between with the entity. However if
+--   no corresponding entity is found, we leave everything alone.
+--
+--   Examples:
+--
+--   >>> replace_entities "Hello, world!"
+--   "Hello, world!"
+--
+--   >>> replace_entities "Hello; world!"
+--   "Hello; world!"
+--
+--   >>> replace_entities "Hello, world & other worlds!"
+--   "Hello, world & other worlds!"
+--
+--   >>> replace_entities "Hello, world & other worlds; hello indeed!"
+--   "Hello, world & other worlds; hello indeed!"
+--
+--   >>> putStrLn $ replace_entities "Hello world—I guess"
+--   Hello world—I guess
+--
 replace_entities :: String -> String
 replace_entities [] = []
 replace_entities ('&':xs) =