A few small improvements ♻

3 files changed, 12 insertions, 11 deletions

diff --git a/src/syntax/ident.rs b/src/syntax/ident.rs
index 55f97f95..4f3668c0 100644
--- a/src/syntax/ident.rs
+++ b/src/syntax/ident.rs
@@ -4,12 +4,13 @@ use std::ops::Deref;
 
 use unicode_xid::UnicodeXID;
 
-/// An identifier as defined by unicode with a few extra permissible characters.
+/// An Unicode identifier with a few extra permissible characters.
 ///
-/// This is defined as in the [Unicode Standard], but allows additionally
-/// `-` and `_` as starting and continuing characters.
+/// In addition to what is specified in the [Unicode Standard][uax31], we allow:
+/// - `_` as a starting character,
+/// - `_` and `-` as continuing characters.
 ///
-/// [Unicode Standard]: http://www.unicode.org/reports/tr31/
+/// [uax31]: http://www.unicode.org/reports/tr31/
 #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd)]
 pub struct Ident(pub String);
 
diff --git a/src/syntax/node.rs b/src/syntax/node.rs
index 866c935e..b7691a70 100644
--- a/src/syntax/node.rs
+++ b/src/syntax/node.rs
@@ -30,16 +30,16 @@ pub enum SynNode {
     Expr(Expr),
 }
 
-/// A section heading.
+/// A section heading: `# ...`.
 #[derive(Debug, Clone, PartialEq)]
 pub struct NodeHeading {
-    /// The section depth (how many hashtags minus 1).
+    /// The section depth (numer of hashtags minus 1).
     pub level: Spanned<u8>,
     /// The contents of the heading.
     pub contents: SynTree,
 }
 
-/// A raw block, rendered in monospace with optional syntax highlighting.
+/// A raw block with optional syntax highlighting: `` `raw` ``.
 ///
 /// Raw blocks start with an arbitrary number of backticks and end with the same
 /// number of backticks. If you want to include a sequence of backticks in a raw
diff --git a/src/syntax/span.rs b/src/syntax/span.rs
index 820de3b3..20008354 100644
--- a/src/syntax/span.rs
+++ b/src/syntax/span.rs
@@ -12,14 +12,14 @@ thread_local! {
 }
 
 /// Annotate a value with a span.
-pub trait SpanWith: Sized {
+pub trait WithSpan: Sized {
     /// Wraps `self` in a `Spanned` with the given span.
-    fn span_with(self, span: impl Into<Span>) -> Spanned<Self> {
+    fn with_span(self, span: impl Into<Span>) -> Spanned<Self> {
         Spanned::new(self, span)
     }
 }
 
-impl<T> SpanWith for T {}
+impl<T> WithSpan for T {}
 
 /// Span offsetting.
 pub trait Offset {
@@ -81,7 +81,7 @@ impl<T> Spanned<Option<T>> {
     /// Swap the spanned and the option.
     pub fn transpose(self) -> Option<Spanned<T>> {
         let Spanned { v, span } = self;
-        v.map(|v| v.span_with(span))
+        v.map(|v| v.with_span(span))
     }
 }