22 files changed, 13 insertions, 36 deletions

diff --git a/crates/hir_expand/src/name.rs b/crates/hir_expand/src/name.rs
index ef67ea2e9..b07fbf8b3 100644
--- a/crates/hir_expand/src/name.rs
+++ b/crates/hir_expand/src/name.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! See [`Name`].
 
 use std::fmt;
 
diff --git a/crates/mbe/src/subtree_source.rs b/crates/mbe/src/subtree_source.rs
index a05cab0f3..bde370fdb 100644
--- a/crates/mbe/src/subtree_source.rs
+++ b/crates/mbe/src/subtree_source.rs
@@ -1,4 +1,6 @@
-//! FIXME: write short doc here
+//! Our parser is generic over the source of tokens it parses.
+//!
+//! This module defines tokens sourced from declarative macros.
 
 use parser::{Token, TokenSource};
 use syntax::{lex_single_syntax_kind, SmolStr, SyntaxKind, SyntaxKind::*, T};
diff --git a/crates/mbe/src/syntax_bridge.rs b/crates/mbe/src/syntax_bridge.rs
index a7c8c13c6..b13168bd3 100644
--- a/crates/mbe/src/syntax_bridge.rs
+++ b/crates/mbe/src/syntax_bridge.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Conversions between [`SyntaxNode`] and [`tt::TokenTree`].
 
 use parser::{FragmentKind, ParseError, TreeSink};
 use rustc_hash::FxHashMap;
diff --git a/crates/mbe/src/tt_iter.rs b/crates/mbe/src/tt_iter.rs
index 195b8cf30..99a8d250b 100644
--- a/crates/mbe/src/tt_iter.rs
+++ b/crates/mbe/src/tt_iter.rs
@@ -1,4 +1,5 @@
-//! FIXME: write short doc here
+//! A "Parser" structure for token trees. We use this when parsing a declarative
+//! macro definition into a list of patterns and templates.
 
 use crate::{subtree_source::SubtreeTokenSource, ExpandError, ExpandResult};
 
diff --git a/crates/parser/src/grammar.rs b/crates/parser/src/grammar.rs
index 9bdf0b5fa..790908aea 100644
--- a/crates/parser/src/grammar.rs
+++ b/crates/parser/src/grammar.rs
@@ -27,6 +27,7 @@
 //! node or an error, rules like `opt_where_clause` may produce nothing.
 //! Non-opt rules typically start with `assert!(p.at(FIRST_TOKEN))`, the
 //! caller is responsible for branching on the first token.
+
 mod attributes;
 mod expressions;
 mod items;
diff --git a/crates/parser/src/grammar/attributes.rs b/crates/parser/src/grammar/attributes.rs
index 124a10eb2..b8242cd2f 100644
--- a/crates/parser/src/grammar/attributes.rs
+++ b/crates/parser/src/grammar/attributes.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) fn inner_attrs(p: &mut Parser) {
diff --git a/crates/parser/src/grammar/expressions.rs b/crates/parser/src/grammar/expressions.rs
index 0d9dc9348..9d22e1950 100644
--- a/crates/parser/src/grammar/expressions.rs
+++ b/crates/parser/src/grammar/expressions.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 mod atom;
 
 pub(crate) use self::atom::{block_expr, match_arm_list};
diff --git a/crates/parser/src/grammar/expressions/atom.rs b/crates/parser/src/grammar/expressions/atom.rs
index 093a9890d..269f223e6 100644
--- a/crates/parser/src/grammar/expressions/atom.rs
+++ b/crates/parser/src/grammar/expressions/atom.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 // test expr_literals
diff --git a/crates/parser/src/grammar/items.rs b/crates/parser/src/grammar/items.rs
index adec74ef3..1057ca8c2 100644
--- a/crates/parser/src/grammar/items.rs
+++ b/crates/parser/src/grammar/items.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 mod consts;
 mod adt;
 mod traits;
diff --git a/crates/parser/src/grammar/items/adt.rs b/crates/parser/src/grammar/items/adt.rs
index 67c0c5697..386d3806c 100644
--- a/crates/parser/src/grammar/items/adt.rs
+++ b/crates/parser/src/grammar/items/adt.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) fn strukt(p: &mut Parser, m: Marker) {
diff --git a/crates/parser/src/grammar/items/consts.rs b/crates/parser/src/grammar/items/consts.rs
index 12130df40..ed3bee4a4 100644
--- a/crates/parser/src/grammar/items/consts.rs
+++ b/crates/parser/src/grammar/items/consts.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) fn static_(p: &mut Parser, m: Marker) {
diff --git a/crates/parser/src/grammar/items/traits.rs b/crates/parser/src/grammar/items/traits.rs
index d3327271c..74f11b45a 100644
--- a/crates/parser/src/grammar/items/traits.rs
+++ b/crates/parser/src/grammar/items/traits.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 // test trait_item
diff --git a/crates/parser/src/grammar/items/use_item.rs b/crates/parser/src/grammar/items/use_item.rs
index 5cb8b08e7..2339d0c69 100644
--- a/crates/parser/src/grammar/items/use_item.rs
+++ b/crates/parser/src/grammar/items/use_item.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) fn use_(p: &mut Parser, m: Marker) {
diff --git a/crates/parser/src/grammar/params.rs b/crates/parser/src/grammar/params.rs
index 9e2f02d43..01ee26a53 100644
--- a/crates/parser/src/grammar/params.rs
+++ b/crates/parser/src/grammar/params.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 // test param_list
diff --git a/crates/parser/src/grammar/paths.rs b/crates/parser/src/grammar/paths.rs
index b10f48fe1..e633646c3 100644
--- a/crates/parser/src/grammar/paths.rs
+++ b/crates/parser/src/grammar/paths.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) const PATH_FIRST: TokenSet =
diff --git a/crates/parser/src/grammar/patterns.rs b/crates/parser/src/grammar/patterns.rs
index f1d1f9eaa..bd092e0af 100644
--- a/crates/parser/src/grammar/patterns.rs
+++ b/crates/parser/src/grammar/patterns.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) const PATTERN_FIRST: TokenSet =
diff --git a/crates/parser/src/grammar/type_args.rs b/crates/parser/src/grammar/type_args.rs
index be36cad17..ed2322e52 100644
--- a/crates/parser/src/grammar/type_args.rs
+++ b/crates/parser/src/grammar/type_args.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) fn opt_generic_arg_list(p: &mut Parser, colon_colon_required: bool) {
diff --git a/crates/parser/src/grammar/type_params.rs b/crates/parser/src/grammar/type_params.rs
index b1f979281..49d6fa6d0 100644
--- a/crates/parser/src/grammar/type_params.rs
+++ b/crates/parser/src/grammar/type_params.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) fn opt_generic_param_list(p: &mut Parser) {
diff --git a/crates/parser/src/grammar/types.rs b/crates/parser/src/grammar/types.rs
index 6ae3e734f..72476c190 100644
--- a/crates/parser/src/grammar/types.rs
+++ b/crates/parser/src/grammar/types.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use super::*;
 
 pub(super) const TYPE_FIRST: TokenSet = paths::PATH_FIRST.union(TokenSet::new(&[
diff --git a/crates/parser/src/parser.rs b/crates/parser/src/parser.rs
index 81e26e009..3f87d98a8 100644
--- a/crates/parser/src/parser.rs
+++ b/crates/parser/src/parser.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! See [`Parser`].
 
 use std::cell::Cell;
 
diff --git a/crates/parser/src/syntax_kind.rs b/crates/parser/src/syntax_kind.rs
index 9ea0e4f9b..4d4377422 100644
--- a/crates/parser/src/syntax_kind.rs
+++ b/crates/parser/src/syntax_kind.rs
@@ -1,4 +1,5 @@
-//! FIXME: write short doc here
+//! Defines [`SyntaxKind`] -- a fieldless enum of all possible syntactic
+//! constructs of the Rust language.
 
 #[macro_use]
 mod generated;
diff --git a/xtask/src/tidy.rs b/xtask/src/tidy.rs
index e31cc2a67..f97e751c5 100644
--- a/xtask/src/tidy.rs
+++ b/xtask/src/tidy.rs
@@ -348,7 +348,7 @@ struct TidyDocs {
 impl TidyDocs {
     fn visit(&mut self, path: &Path, text: &str) {
         // Tests and diagnostic fixes don't need module level comments.
-        if is_exclude_dir(path, &["tests", "test_data", "fixes"]) {
+        if is_exclude_dir(path, &["tests", "test_data", "fixes", "grammar"]) {
             return;
         }
 
@@ -392,7 +392,7 @@ impl TidyDocs {
             )
         }
 
-        let poorly_documented = ["hir_expand", "mbe", "parser", "hir_ty"];
+        let poorly_documented = ["hir_ty"];
 
         let mut has_fixmes =
             poorly_documented.iter().map(|it| (*it, false)).collect::<HashMap<&str, bool>>();