9 files changed, 384 insertions, 112 deletions

diff --git a/crates/assists/src/handlers/fill_match_arms.rs b/crates/assists/src/handlers/fill_match_arms.rs
index da47187e4..7663d211d 100644
--- a/crates/assists/src/handlers/fill_match_arms.rs
+++ b/crates/assists/src/handlers/fill_match_arms.rs
@@ -8,7 +8,7 @@ use syntax::ast::{self, make, AstNode, MatchArm, NameOwner, Pat};
 use test_utils::mark;
 
 use crate::{
-    utils::{render_snippet, Cursor},
+    utils::{does_pat_match_variant, render_snippet, Cursor},
     AssistContext, AssistId, AssistKind, Assists,
 };
 
@@ -147,25 +147,6 @@ fn is_variant_missing(existing_arms: &mut Vec<MatchArm>, var: &Pat) -> bool {
     })
 }
 
-fn does_pat_match_variant(pat: &Pat, var: &Pat) -> bool {
-    let first_node_text = |pat: &Pat| pat.syntax().first_child().map(|node| node.text());
-
-    let pat_head = match pat {
-        Pat::IdentPat(bind_pat) => {
-            if let Some(p) = bind_pat.pat() {
-                first_node_text(&p)
-            } else {
-                return false;
-            }
-        }
-        pat => first_node_text(pat),
-    };
-
-    let var_head = first_node_text(var);
-
-    pat_head == var_head
-}
-
 fn resolve_enum_def(sema: &Semantics<RootDatabase>, expr: &ast::Expr) -> Option<hir::Enum> {
     sema.type_of_expr(&expr)?.autoderef(sema.db).find_map(|ty| match ty.as_adt() {
         Some(Adt::Enum(e)) => Some(e),
diff --git a/crates/assists/src/handlers/replace_if_let_with_match.rs b/crates/assists/src/handlers/replace_if_let_with_match.rs
index aee3397ab..aee880625 100644
--- a/crates/assists/src/handlers/replace_if_let_with_match.rs
+++ b/crates/assists/src/handlers/replace_if_let_with_match.rs
@@ -10,7 +10,10 @@ use syntax::{
     AstNode,
 };
 
-use crate::{utils::unwrap_trivial_block, AssistContext, AssistId, AssistKind, Assists};
+use crate::{
+    utils::{does_pat_match_variant, unwrap_trivial_block},
+    AssistContext, AssistId, AssistKind, Assists,
+};
 
 // Assist: replace_if_let_with_match
 //
@@ -66,7 +69,13 @@ pub(crate) fn replace_if_let_with_match(acc: &mut Assists, ctx: &AssistContext)
                         .sema
                         .type_of_pat(&pat)
                         .and_then(|ty| TryEnum::from_ty(&ctx.sema, &ty))
-                        .map(|it| it.sad_pattern())
+                        .map(|it| {
+                            if does_pat_match_variant(&pat, &it.sad_pattern()) {
+                                it.happy_pattern()
+                            } else {
+                                it.sad_pattern()
+                            }
+                        })
                         .unwrap_or_else(|| make::wildcard_pat().into());
                     let else_expr = unwrap_trivial_block(else_block);
                     make::match_arm(vec![pattern], else_expr)
@@ -279,6 +288,36 @@ fn foo(x: Option<i32>) {
     }
 
     #[test]
+    fn special_case_inverted_option() {
+        check_assist(
+            replace_if_let_with_match,
+            r#"
+enum Option<T> { Some(T), None }
+use Option::*;
+
+fn foo(x: Option<i32>) {
+    $0if let None = x {
+        println!("none")
+    } else {
+        println!("some")
+    }
+}
+           "#,
+            r#"
+enum Option<T> { Some(T), None }
+use Option::*;
+
+fn foo(x: Option<i32>) {
+    match x {
+        None => println!("none"),
+        Some(_) => println!("some"),
+    }
+}
+           "#,
+        );
+    }
+
+    #[test]
     fn special_case_result() {
         check_assist(
             replace_if_let_with_match,
@@ -309,6 +348,36 @@ fn foo(x: Result<i32, ()>) {
     }
 
     #[test]
+    fn special_case_inverted_result() {
+        check_assist(
+            replace_if_let_with_match,
+            r#"
+enum Result<T, E> { Ok(T), Err(E) }
+use Result::*;
+
+fn foo(x: Result<i32, ()>) {
+    $0if let Err(x) = x {
+        println!("{}", x)
+    } else {
+        println!("ok")
+    }
+}
+           "#,
+            r#"
+enum Result<T, E> { Ok(T), Err(E) }
+use Result::*;
+
+fn foo(x: Result<i32, ()>) {
+    match x {
+        Err(x) => println!("{}", x),
+        Ok(_) => println!("ok"),
+    }
+}
+           "#,
+        );
+    }
+
+    #[test]
     fn nested_indent() {
         check_assist(
             replace_if_let_with_match,
diff --git a/crates/assists/src/utils.rs b/crates/assists/src/utils.rs
index 44c35bafa..4e762e18b 100644
--- a/crates/assists/src/utils.rs
+++ b/crates/assists/src/utils.rs
@@ -248,3 +248,22 @@ fn invert_special_case(expr: &ast::Expr) -> Option<ast::Expr> {
 pub(crate) fn next_prev() -> impl Iterator<Item = Direction> {
     [Direction::Next, Direction::Prev].iter().copied()
 }
+
+pub(crate) fn does_pat_match_variant(pat: &ast::Pat, var: &ast::Pat) -> bool {
+    let first_node_text = |pat: &ast::Pat| pat.syntax().first_child().map(|node| node.text());
+
+    let pat_head = match pat {
+        ast::Pat::IdentPat(bind_pat) => {
+            if let Some(p) = bind_pat.pat() {
+                first_node_text(&p)
+            } else {
+                return pat.syntax().text() == var.syntax().text();
+            }
+        }
+        pat => first_node_text(pat),
+    };
+
+    let var_head = first_node_text(var);
+
+    pat_head == var_head
+}
diff --git a/crates/ide_db/src/ty_filter.rs b/crates/ide_db/src/ty_filter.rs
index 63a945282..f8406851b 100644
--- a/crates/ide_db/src/ty_filter.rs
+++ b/crates/ide_db/src/ty_filter.rs
@@ -49,6 +49,21 @@ impl TryEnum {
         }
     }
 
+    pub fn happy_pattern(self) -> ast::Pat {
+        match self {
+            TryEnum::Result => make::tuple_struct_pat(
+                make::path_unqualified(make::path_segment(make::name_ref("Ok"))),
+                iter::once(make::wildcard_pat().into()),
+            )
+            .into(),
+            TryEnum::Option => make::tuple_struct_pat(
+                make::path_unqualified(make::path_segment(make::name_ref("Some"))),
+                iter::once(make::wildcard_pat().into()),
+            )
+            .into(),
+        }
+    }
+
     fn type_name(self) -> &'static str {
         match self {
             TryEnum::Result => "Result",
diff --git a/crates/mbe/Cargo.toml b/crates/mbe/Cargo.toml
index af80e2be3..43bc10490 100644
--- a/crates/mbe/Cargo.toml
+++ b/crates/mbe/Cargo.toml
@@ -17,6 +17,5 @@ log = "0.4.8"
 syntax = { path = "../syntax", version = "0.0.0" }
 parser = { path = "../parser", version = "0.0.0" }
 tt = { path = "../tt", version = "0.0.0" }
-
-[dev-dependencies]
 test_utils = { path = "../test_utils" }
+
diff --git a/crates/mbe/src/lib.rs b/crates/mbe/src/lib.rs
index 19543d777..35cde5f10 100644
--- a/crates/mbe/src/lib.rs
+++ b/crates/mbe/src/lib.rs
@@ -14,6 +14,7 @@ mod tests;
 
 use std::fmt;
 
+use test_utils::mark;
 pub use tt::{Delimiter, DelimiterKind, Punct};
 
 use crate::{
@@ -76,6 +77,14 @@ pub struct MacroRules {
     shift: Shift,
 }
 
+/// For Macro 2.0
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MacroDef {
+    rules: Vec<Rule>,
+    /// Highest id of the token we have in TokenMap
+    shift: Shift,
+}
+
 #[derive(Clone, Debug, PartialEq, Eq)]
 struct Rule {
     lhs: MetaTemplate,
@@ -179,7 +188,7 @@ impl MacroRules {
         let mut src = TtIter::new(tt);
         let mut rules = Vec::new();
         while src.len() > 0 {
-            let rule = Rule::parse(&mut src)?;
+            let rule = Rule::parse(&mut src, true)?;
             rules.push(rule);
             if let Err(()) = src.expect_char(';') {
                 if src.len() > 0 {
@@ -200,7 +209,58 @@ impl MacroRules {
         // apply shift
         let mut tt = tt.clone();
         self.shift.shift_all(&mut tt);
-        mbe_expander::expand(self, &tt)
+        mbe_expander::expand_rules(&self.rules, &tt)
+    }
+
+    pub fn map_id_down(&self, id: tt::TokenId) -> tt::TokenId {
+        self.shift.shift(id)
+    }
+
+    pub fn map_id_up(&self, id: tt::TokenId) -> (tt::TokenId, Origin) {
+        match self.shift.unshift(id) {
+            Some(id) => (id, Origin::Call),
+            None => (id, Origin::Def),
+        }
+    }
+}
+
+impl MacroDef {
+    pub fn parse(tt: &tt::Subtree) -> Result<MacroDef, ParseError> {
+        let mut src = TtIter::new(tt);
+        let mut rules = Vec::new();
+
+        if Some(tt::DelimiterKind::Brace) == tt.delimiter_kind() {
+            mark::hit!(parse_macro_def_rules);
+            while src.len() > 0 {
+                let rule = Rule::parse(&mut src, true)?;
+                rules.push(rule);
+                if let Err(()) = src.expect_char(';') {
+                    if src.len() > 0 {
+                        return Err(ParseError::Expected("expected `;`".to_string()));
+                    }
+                    break;
+                }
+            }
+        } else {
+            mark::hit!(parse_macro_def_simple);
+            let rule = Rule::parse(&mut src, false)?;
+            if src.len() != 0 {
+                return Err(ParseError::Expected("remain tokens in macro def".to_string()));
+            }
+            rules.push(rule);
+        }
+        for rule in rules.iter() {
+            validate(&rule.lhs)?;
+        }
+
+        Ok(MacroDef { rules, shift: Shift::new(tt) })
+    }
+
+    pub fn expand(&self, tt: &tt::Subtree) -> ExpandResult<tt::Subtree> {
+        // apply shift
+        let mut tt = tt.clone();
+        self.shift.shift_all(&mut tt);
+        mbe_expander::expand_rules(&self.rules, &tt)
     }
 
     pub fn map_id_down(&self, id: tt::TokenId) -> tt::TokenId {
@@ -216,12 +276,14 @@ impl MacroRules {
 }
 
 impl Rule {
-    fn parse(src: &mut TtIter) -> Result<Rule, ParseError> {
+    fn parse(src: &mut TtIter, expect_arrow: bool) -> Result<Rule, ParseError> {
         let lhs = src
             .expect_subtree()
             .map_err(|()| ParseError::Expected("expected subtree".to_string()))?;
-        src.expect_char('=').map_err(|()| ParseError::Expected("expected `=`".to_string()))?;
-        src.expect_char('>').map_err(|()| ParseError::Expected("expected `>`".to_string()))?;
+        if expect_arrow {
+            src.expect_char('=').map_err(|()| ParseError::Expected("expected `=`".to_string()))?;
+            src.expect_char('>').map_err(|()| ParseError::Expected("expected `>`".to_string()))?;
+        }
         let rhs = src
             .expect_subtree()
             .map_err(|()| ParseError::Expected("expected subtree".to_string()))?;
diff --git a/crates/mbe/src/mbe_expander.rs b/crates/mbe/src/mbe_expander.rs
index a80b73db4..802c8fb0f 100644
--- a/crates/mbe/src/mbe_expander.rs
+++ b/crates/mbe/src/mbe_expander.rs
@@ -10,11 +10,10 @@ use syntax::SmolStr;
 
 use crate::{ExpandError, ExpandResult};
 
-pub(crate) fn expand(rules: &crate::MacroRules, input: &tt::Subtree) -> ExpandResult<tt::Subtree> {
-    expand_rules(&rules.rules, input)
-}
-
-fn expand_rules(rules: &[crate::Rule], input: &tt::Subtree) -> ExpandResult<tt::Subtree> {
+pub(crate) fn expand_rules(
+    rules: &[crate::Rule],
+    input: &tt::Subtree,
+) -> ExpandResult<tt::Subtree> {
     let mut match_: Option<(matcher::Match, &crate::Rule)> = None;
     for rule in rules {
         let new_match = match matcher::match_(&rule.lhs, input) {
diff --git a/crates/mbe/src/tests.rs b/crates/mbe/src/tests.rs
index bd2977ebd..8d978163d 100644
--- a/crates/mbe/src/tests.rs
+++ b/crates/mbe/src/tests.rs
@@ -6,7 +6,7 @@ use syntax::{
     SyntaxKind::{ERROR, IDENT},
     SyntaxNode, WalkEvent, T,
 };
-use test_utils::assert_eq_text;
+use test_utils::{assert_eq_text, mark};
 
 use super::*;
 
@@ -675,6 +675,36 @@ fn test_match_literal() {
     .assert_expand_items("foo! ['('];", "fn foo () {}");
 }
 
+#[test]
+fn test_parse_macro_def_simple() {
+    mark::check!(parse_macro_def_simple);
+
+    parse_macro2(
+        r#"
+macro foo($id:ident) {
+    fn $id() {}
+}
+"#,
+    )
+    .assert_expand_items("foo!(bar);", "fn bar () {}");
+}
+
+#[test]
+fn test_parse_macro_def_rules() {
+    mark::check!(parse_macro_def_rules);
+
+    parse_macro2(
+        r#"
+macro foo {
+    ($id:ident) => {
+        fn $id() {}
+    }
+}
+"#,
+    )
+    .assert_expand_items("foo!(bar);", "fn bar () {}");
+}
+
 // The following tests are port from intellij-rust directly
 // https://github.com/intellij-rust/intellij-rust/blob/c4e9feee4ad46e7953b1948c112533360b6087bb/src/test/kotlin/org/rust/lang/core/macros/RsMacroExpansionTest.kt
 
@@ -1699,95 +1729,122 @@ pub(crate) struct MacroFixture {
     rules: MacroRules,
 }
 
-impl MacroFixture {
-    pub(crate) fn expand_tt(&self, invocation: &str) -> tt::Subtree {
-        self.try_expand_tt(invocation).unwrap()
-    }
-
-    fn try_expand_tt(&self, invocation: &str) -> Result<tt::Subtree, ExpandError> {
-        let source_file = ast::SourceFile::parse(invocation).tree();
-        let macro_invocation =
-            source_file.syntax().descendants().find_map(ast::MacroCall::cast).unwrap();
-
-        let (invocation_tt, _) = ast_to_token_tree(&macro_invocation.token_tree().unwrap())
-            .ok_or_else(|| ExpandError::ConversionError)?;
+pub(crate) struct MacroFixture2 {
+    rules: MacroDef,
+}
 
-        self.rules.expand(&invocation_tt).result()
-    }
+macro_rules! impl_fixture {
+    ($name:ident) => {
+        impl $name {
+            pub(crate) fn expand_tt(&self, invocation: &str) -> tt::Subtree {
+                self.try_expand_tt(invocation).unwrap()
+            }
 
-    fn assert_expand_err(&self, invocation: &str, err: &ExpandError) {
-        assert_eq!(self.try_expand_tt(invocation).as_ref(), Err(err));
-    }
+            fn try_expand_tt(&self, invocation: &str) -> Result<tt::Subtree, ExpandError> {
+                let source_file = ast::SourceFile::parse(invocation).tree();
+                let macro_invocation =
+                    source_file.syntax().descendants().find_map(ast::MacroCall::cast).unwrap();
 
-    fn expand_items(&self, invocation: &str) -> SyntaxNode {
-        let expanded = self.expand_tt(invocation);
-        token_tree_to_syntax_node(&expanded, FragmentKind::Items).unwrap().0.syntax_node()
-    }
+                let (invocation_tt, _) = ast_to_token_tree(&macro_invocation.token_tree().unwrap())
+                    .ok_or_else(|| ExpandError::ConversionError)?;
 
-    fn expand_statements(&self, invocation: &str) -> SyntaxNode {
-        let expanded = self.expand_tt(invocation);
-        token_tree_to_syntax_node(&expanded, FragmentKind::Statements).unwrap().0.syntax_node()
-    }
+                self.rules.expand(&invocation_tt).result()
+            }
 
-    fn expand_expr(&self, invocation: &str) -> SyntaxNode {
-        let expanded = self.expand_tt(invocation);
-        token_tree_to_syntax_node(&expanded, FragmentKind::Expr).unwrap().0.syntax_node()
-    }
+            #[allow(unused)]
+            fn assert_expand_err(&self, invocation: &str, err: &ExpandError) {
+                assert_eq!(self.try_expand_tt(invocation).as_ref(), Err(err));
+            }
 
-    fn assert_expand_tt(&self, invocation: &str, expected: &str) {
-        let expansion = self.expand_tt(invocation);
-        assert_eq!(expansion.to_string(), expected);
-    }
+            #[allow(unused)]
+            fn expand_items(&self, invocation: &str) -> SyntaxNode {
+                let expanded = self.expand_tt(invocation);
+                token_tree_to_syntax_node(&expanded, FragmentKind::Items).unwrap().0.syntax_node()
+            }
 
-    fn assert_expand(&self, invocation: &str, expected: &str) {
-        let expansion = self.expand_tt(invocation);
-        let actual = format!("{:?}", expansion);
-        test_utils::assert_eq_text!(&expected.trim(), &actual.trim());
-    }
+            #[allow(unused)]
+            fn expand_statements(&self, invocation: &str) -> SyntaxNode {
+                let expanded = self.expand_tt(invocation);
+                token_tree_to_syntax_node(&expanded, FragmentKind::Statements)
+                    .unwrap()
+                    .0
+                    .syntax_node()
+            }
 
-    fn assert_expand_items(&self, invocation: &str, expected: &str) -> &MacroFixture {
-        self.assert_expansion(FragmentKind::Items, invocation, expected);
-        self
-    }
+            #[allow(unused)]
+            fn expand_expr(&self, invocation: &str) -> SyntaxNode {
+                let expanded = self.expand_tt(invocation);
+                token_tree_to_syntax_node(&expanded, FragmentKind::Expr).unwrap().0.syntax_node()
+            }
 
-    fn assert_expand_statements(&self, invocation: &str, expected: &str) -> &MacroFixture {
-        self.assert_expansion(FragmentKind::Statements, invocation, expected);
-        self
-    }
+            #[allow(unused)]
+            fn assert_expand_tt(&self, invocation: &str, expected: &str) {
+                let expansion = self.expand_tt(invocation);
+                assert_eq!(expansion.to_string(), expected);
+            }
 
-    fn assert_expansion(&self, kind: FragmentKind, invocation: &str, expected: &str) {
-        let expanded = self.expand_tt(invocation);
-        assert_eq!(expanded.to_string(), expected);
-
-        let expected = expected.replace("$crate", "C_C__C");
-
-        // wrap the given text to a macro call
-        let expected = {
-            let wrapped = format!("wrap_macro!( {} )", expected);
-            let wrapped = ast::SourceFile::parse(&wrapped);
-            let wrapped =
-                wrapped.tree().syntax().descendants().find_map(ast::TokenTree::cast).unwrap();
-            let mut wrapped = ast_to_token_tree(&wrapped).unwrap().0;
-            wrapped.delimiter = None;
-            wrapped
-        };
+            #[allow(unused)]
+            fn assert_expand(&self, invocation: &str, expected: &str) {
+                let expansion = self.expand_tt(invocation);
+                let actual = format!("{:?}", expansion);
+                test_utils::assert_eq_text!(&expected.trim(), &actual.trim());
+            }
 
-        let expanded_tree = token_tree_to_syntax_node(&expanded, kind).unwrap().0.syntax_node();
-        let expanded_tree = debug_dump_ignore_spaces(&expanded_tree).trim().to_string();
+            fn assert_expand_items(&self, invocation: &str, expected: &str) -> &$name {
+                self.assert_expansion(FragmentKind::Items, invocation, expected);
+                self
+            }
 
-        let expected_tree = token_tree_to_syntax_node(&expected, kind).unwrap().0.syntax_node();
-        let expected_tree = debug_dump_ignore_spaces(&expected_tree).trim().to_string();
+            #[allow(unused)]
+            fn assert_expand_statements(&self, invocation: &str, expected: &str) -> &$name {
+                self.assert_expansion(FragmentKind::Statements, invocation, expected);
+                self
+            }
 
-        let expected_tree = expected_tree.replace("C_C__C", "$crate");
-        assert_eq!(
-            expanded_tree, expected_tree,
-            "\nleft:\n{}\nright:\n{}",
-            expanded_tree, expected_tree,
-        );
-    }
+            fn assert_expansion(&self, kind: FragmentKind, invocation: &str, expected: &str) {
+                let expanded = self.expand_tt(invocation);
+                assert_eq!(expanded.to_string(), expected);
+
+                let expected = expected.replace("$crate", "C_C__C");
+
+                // wrap the given text to a macro call
+                let expected = {
+                    let wrapped = format!("wrap_macro!( {} )", expected);
+                    let wrapped = ast::SourceFile::parse(&wrapped);
+                    let wrapped = wrapped
+                        .tree()
+                        .syntax()
+                        .descendants()
+                        .find_map(ast::TokenTree::cast)
+                        .unwrap();
+                    let mut wrapped = ast_to_token_tree(&wrapped).unwrap().0;
+                    wrapped.delimiter = None;
+                    wrapped
+                };
+
+                let expanded_tree =
+                    token_tree_to_syntax_node(&expanded, kind).unwrap().0.syntax_node();
+                let expanded_tree = debug_dump_ignore_spaces(&expanded_tree).trim().to_string();
+
+                let expected_tree =
+                    token_tree_to_syntax_node(&expected, kind).unwrap().0.syntax_node();
+                let expected_tree = debug_dump_ignore_spaces(&expected_tree).trim().to_string();
+
+                let expected_tree = expected_tree.replace("C_C__C", "$crate");
+                assert_eq!(
+                    expanded_tree, expected_tree,
+                    "\nleft:\n{}\nright:\n{}",
+                    expanded_tree, expected_tree,
+                );
+            }
+        }
+    };
 }
 
-fn parse_macro_to_tt(ra_fixture: &str) -> tt::Subtree {
+impl_fixture!(MacroFixture);
+impl_fixture!(MacroFixture2);
+
+fn parse_macro_rules_to_tt(ra_fixture: &str) -> tt::Subtree {
     let source_file = ast::SourceFile::parse(ra_fixture).ok().unwrap();
     let macro_definition =
         source_file.syntax().descendants().find_map(ast::MacroRules::cast).unwrap();
@@ -1804,14 +1861,36 @@ fn parse_macro_to_tt(ra_fixture: &str) -> tt::Subtree {
     definition_tt
 }
 
+fn parse_macro_def_to_tt(ra_fixture: &str) -> tt::Subtree {
+    let source_file = ast::SourceFile::parse(ra_fixture).ok().unwrap();
+    let macro_definition =
+        source_file.syntax().descendants().find_map(ast::MacroDef::cast).unwrap();
+
+    let (definition_tt, _) = ast_to_token_tree(&macro_definition.body().unwrap()).unwrap();
+
+    let parsed =
+        parse_to_token_tree(&ra_fixture[macro_definition.body().unwrap().syntax().text_range()])
+            .unwrap()
+            .0;
+    assert_eq!(definition_tt, parsed);
+
+    definition_tt
+}
+
 pub(crate) fn parse_macro(ra_fixture: &str) -> MacroFixture {
-    let definition_tt = parse_macro_to_tt(ra_fixture);
+    let definition_tt = parse_macro_rules_to_tt(ra_fixture);
     let rules = MacroRules::parse(&definition_tt).unwrap();
     MacroFixture { rules }
 }
 
+pub(crate) fn parse_macro2(ra_fixture: &str) -> MacroFixture2 {
+    let definition_tt = parse_macro_def_to_tt(ra_fixture);
+    let rules = MacroDef::parse(&definition_tt).unwrap();
+    MacroFixture2 { rules }
+}
+
 pub(crate) fn parse_macro_error(ra_fixture: &str) -> ParseError {
-    let definition_tt = parse_macro_to_tt(ra_fixture);
+    let definition_tt = parse_macro_rules_to_tt(ra_fixture);
 
     match MacroRules::parse(&definition_tt) {
         Ok(_) => panic!("Expect error"),
diff --git a/crates/paths/src/lib.rs b/crates/paths/src/lib.rs
index 1b259682d..22011cb33 100644
--- a/crates/paths/src/lib.rs
+++ b/crates/paths/src/lib.rs
@@ -6,6 +6,7 @@ use std::{
     path::{Component, Path, PathBuf},
 };
 
+/// Wrapper around an absolute [`PathBuf`].
 #[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
 pub struct AbsPathBuf(PathBuf);
 
@@ -58,18 +59,33 @@ impl PartialEq<AbsPath> for AbsPathBuf {
 }
 
 impl AbsPathBuf {
+    /// Wrap the given absolute path in `AbsPathBuf`
+    ///
+    /// # Panics
+    ///
+    /// Panics if `path` is not absolute.
     pub fn assert(path: PathBuf) -> AbsPathBuf {
         AbsPathBuf::try_from(path)
             .unwrap_or_else(|path| panic!("expected absolute path, got {}", path.display()))
     }
+
+    /// Coerces to a `AbsPath` slice.
+    ///
+    /// Equivalent of [`PathBuf::as_path`] for `AbsPathBuf`.
     pub fn as_path(&self) -> &AbsPath {
         AbsPath::assert(self.0.as_path())
     }
+
+    /// Equivalent of [`PathBuf::pop`] for `AbsPathBuf`.
+    ///
+    /// Note that this won't remove the root component, so `self` will still be
+    /// absolute.
     pub fn pop(&mut self) -> bool {
         self.0.pop()
     }
 }
 
+/// Wrapper around an absolute [`Path`].
 #[derive(Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
 #[repr(transparent)]
 pub struct AbsPath(Path);
@@ -98,28 +114,56 @@ impl<'a> TryFrom<&'a Path> for &'a AbsPath {
 }
 
 impl AbsPath {
+    /// Wrap the given absolute path in `AbsPath`
+    ///
+    /// # Panics
+    ///
+    /// Panics if `path` is not absolute.
     pub fn assert(path: &Path) -> &AbsPath {
         assert!(path.is_absolute());
         unsafe { &*(path as *const Path as *const AbsPath) }
     }
 
+    /// Equivalent of [`Path::parent`] for `AbsPath`.
     pub fn parent(&self) -> Option<&AbsPath> {
         self.0.parent().map(AbsPath::assert)
     }
+
+    /// Equivalent of [`Path::join`] for `AbsPath`.
     pub fn join(&self, path: impl AsRef<Path>) -> AbsPathBuf {
         self.as_ref().join(path).try_into().unwrap()
     }
+
+    /// Normalize the given path:
+    /// - Removes repeated separators: `/a//b` becomes `/a/b`
+    /// - Removes occurrences of `.` and resolves `..`.
+    /// - Removes trailing slashes: `/a/b/` becomes `/a/b`.
+    ///
+    /// # Example
+    /// ```
+    /// # use paths::AbsPathBuf;
+    /// let abs_path_buf = AbsPathBuf::assert("/a/../../b/.//c//".into());
+    /// let normalized = abs_path_buf.normalize();
+    /// assert_eq!(normalized, AbsPathBuf::assert("/b/c".into()));
+    /// ```
     pub fn normalize(&self) -> AbsPathBuf {
         AbsPathBuf(normalize_path(&self.0))
     }
+
+    /// Equivalent of [`Path::to_path_buf`] for `AbsPath`.
     pub fn to_path_buf(&self) -> AbsPathBuf {
         AbsPathBuf::try_from(self.0.to_path_buf()).unwrap()
     }
+
+    /// Equivalent of [`Path::strip_prefix`] for `AbsPath`.
+    ///
+    /// Returns a relative path.
     pub fn strip_prefix(&self, base: &AbsPath) -> Option<&RelPath> {
         self.0.strip_prefix(base).ok().map(RelPath::new_unchecked)
     }
 }
 
+/// Wrapper around a relative [`PathBuf`].
 #[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
 pub struct RelPathBuf(PathBuf);
 
@@ -160,11 +204,15 @@ impl TryFrom<&str> for RelPathBuf {
 }
 
 impl RelPathBuf {
+    /// Coerces to a `RelPath` slice.
+    ///
+    /// Equivalent of [`PathBuf::as_path`] for `RelPathBuf`.
     pub fn as_path(&self) -> &RelPath {
         RelPath::new_unchecked(self.0.as_path())
     }
 }
 
+/// Wrapper around a relative [`Path`].
 #[derive(Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
 #[repr(transparent)]
 pub struct RelPath(Path);
@@ -183,12 +231,13 @@ impl AsRef<Path> for RelPath {
 }
 
 impl RelPath {
+    /// Creates a new `RelPath` from `path`, without checking if it is relative.
     pub fn new_unchecked(path: &Path) -> &RelPath {
         unsafe { &*(path as *const Path as *const RelPath) }
     }
 }
 
-// https://github.com/rust-lang/cargo/blob/79c769c3d7b4c2cf6a93781575b7f592ef974255/src/cargo/util/paths.rs#L60-L85
+/// Taken from https://github.com/rust-lang/cargo/blob/79c769c3d7b4c2cf6a93781575b7f592ef974255/src/cargo/util/paths.rs#L60-L85
 fn normalize_path(path: &Path) -> PathBuf {
     let mut components = path.components().peekable();
     let mut ret = if let Some(c @ Component::Prefix(..)) = components.peek().cloned() {