From 129ea34b18aaf7f5a01d404effbdc78cbbe67a74 Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Tue, 14 Jun 2022 14:17:15 +0200
Subject: Add examples to some docs

---
 src/compiler.rs                        | 48 ++++++++++++++++++++++++++++++++++
 src/util/decode_character_reference.rs |  4 +--
 src/util/sanitize_uri.rs               | 20 ++++++++++++++
 3 files changed, 70 insertions(+), 2 deletions(-)

(limited to 'src')

diff --git a/src/compiler.rs b/src/compiler.rs
index e1ce440..2a3f101 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -14,11 +14,59 @@ pub struct CompileOptions {
     /// Whether to allow (dangerous) HTML.
     /// The default is `false`, you can turn it on to `true` for trusted
     /// content.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use micromark::{micromark, micromark_with_options, CompileOptions};
+    ///
+    /// // micromark is safe by default:
+    /// assert_eq!(
+    ///     micromark("Hi, <i>venus</i>!"),
+    ///     "<p>Hi, &lt;i&gt;venus&lt;/i&gt;!</p>"
+    /// );
+    ///
+    /// // Turn `allow_dangerous_html` on to allow potentially dangerous HTML:
+    /// assert_eq!(
+    ///     micromark_with_options(
+    ///         "Hi, <i>venus</i>!",
+    ///         &CompileOptions {
+    ///             allow_dangerous_html: true,
+    ///             allow_dangerous_protocol: false,
+    ///         }
+    ///     ),
+    ///     "<p>Hi, <i>venus</i>!</p>"
+    /// );
+    /// ```
     pub allow_dangerous_html: bool,
 
     /// Whether to allow (dangerous) protocols in links and images.
     /// The default is `false`, you can turn it on to `true` for trusted
     /// content.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use micromark::{micromark, micromark_with_options, CompileOptions};
+    ///
+    /// // micromark is safe by default:
+    /// assert_eq!(
+    ///     micromark("<javascript:alert(1)>"),
+    ///     "<p><a href=\"\">javascript:alert(1)</a></p>"
+    /// );
+    ///
+    /// // Turn `allow_dangerous_protocol` on to allow potentially dangerous protocols:
+    /// assert_eq!(
+    ///     micromark_with_options(
+    ///         "<javascript:alert(1)>",
+    ///         &CompileOptions {
+    ///             allow_dangerous_html: false,
+    ///             allow_dangerous_protocol: true,
+    ///         }
+    ///     ),
+    ///     "<p><a href=\"javascript:alert(1)\">javascript:alert(1)</a></p>"
+    /// );
+    /// ```
     pub allow_dangerous_protocol: bool,
 }
 
diff --git a/src/util/decode_character_reference.rs b/src/util/decode_character_reference.rs
index 4a9317e..9be531b 100644
--- a/src/util/decode_character_reference.rs
+++ b/src/util/decode_character_reference.rs
@@ -15,7 +15,7 @@ use crate::constant::{CHARACTER_REFERENCE_NAMES, CHARACTER_REFERENCE_VALUES};
 /// ## Examples
 ///
 /// ```rust ignore
-/// use micromark::util::character_reference::decode_named;
+/// use micromark::util::decode_character_reference::decode_named;
 ///
 /// assert_eq!(decode_named("amp"), "&");
 /// assert_eq!(decode_named("AElig"), "Æ");
@@ -58,7 +58,7 @@ pub fn decode_named(value: &str) -> String {
 /// ## Examples
 ///
 /// ```rust ignore
-/// use micromark::util::character_reference::decode_numeric;
+/// use micromark::util::decode_character_reference::decode_numeric;
 ///
 /// assert_eq!(decode_numeric("123", 10), '{');
 /// assert_eq!(decode_numeric("9", 16), '\t');
diff --git a/src/util/sanitize_uri.rs b/src/util/sanitize_uri.rs
index 1dffc50..40e0f2c 100644
--- a/src/util/sanitize_uri.rs
+++ b/src/util/sanitize_uri.rs
@@ -17,6 +17,17 @@ use crate::util::encode::encode;
 /// If the URL includes an unknown protocol (one not matched by `protocol`, such
 /// as a dangerous example, `javascript:`), the value is ignored.
 ///
+/// ## Examples
+///
+/// ```rust ignore
+/// use micromark::util::sanitize_url::sanitize_url;
+///
+/// assert_eq!(sanitize_uri("javascript:alert(1)", &None), "javascript:alert(1)");
+/// assert_eq!(sanitize_uri("javascript:alert(1)", &Some(vec!["http", "https"])), "");
+/// assert_eq!(sanitize_uri("https://example.com", &Some(vec!["http", "https"])), "https://example.com");
+/// assert_eq!(sanitize_uri("https://a👍b.c/%20/%", &Some(vec!["http", "https"])), "https://a%F0%9F%91%8Db.c/%20/%25");
+/// ```
+///
 /// ## References
 ///
 /// *   [`micromark-util-sanitize-uri` in `micromark`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-sanitize-uri)
@@ -61,6 +72,15 @@ pub fn sanitize_uri(value: &str, protocols: &Option<Vec<&str>>) -> String {
 /// Encode unsafe characters with percent-encoding, skipping already encoded
 /// sequences.
 ///
+/// ## Examples
+///
+/// ```rust ignore
+/// use micromark::util::sanitize_url::normalize_uri;
+///
+/// assert_eq!(sanitize_uri("https://example.com"), "https://example.com");
+/// assert_eq!(sanitize_uri("https://a👍b.c/%20/%"), "https://a%F0%9F%91%8Db.c/%20/%25");
+/// ```
+///
 /// ## References
 ///
 /// *   [`micromark-util-sanitize-uri` in `micromark`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-sanitize-uri)
-- 
cgit