From fb9f0c448f286aaf1b85535dc9356562e4be48e1 Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Mon, 12 Aug 2024 12:15:16 -0700 Subject: [PATCH] [red-knot] cleanup doc comments and attributes (#12792) Make `cargo doc -p red_knot_python_semantic --document-private-items` run warning-free. I'd still like to do this for all of ruff and start enforcing it in CI (https://github.com/astral-sh/ruff/issues/12372) but haven't gotten to it yet. But in the meantime I'm trying to maintain it for at least `red_knot_python_semantic`, as it helps to ensure our doc comments stay up to date. A few of the comments I just removed or shortened, as their continued relevance wasn't clear to me; please object in review if you think some of them are important to keep! Also remove a no-longer-needed `allow` attribute. --- .github/workflows/ci.yaml | 7 +++++++ crates/red_knot_python_semantic/src/semantic_index.rs | 6 ++---- .../red_knot_python_semantic/src/semantic_index/ast_ids.rs | 4 ++-- crates/red_knot_python_semantic/src/types/infer.rs | 3 +-- 4 files changed, 12 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index f3ad87ed98de0..17e1af11ac7e8 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -142,6 +142,13 @@ jobs: # Check for broken links in the documentation. - run: cargo doc --all --no-deps + env: + RUSTDOCFLAGS: "-D warnings" + # Use --document-private-items so that all our doc comments are kept in + # sync, not just public items. Eventually we should do this for all + # crates; for now add crates here as they are warning-clean to prevent + # regression. + - run: cargo doc --no-deps -p red_knot_python_semantic -p red_knot -p ruff_db --document-private-items env: # Setting RUSTDOCFLAGS because `cargo doc --check` isn't yet implemented (https://github.com/rust-lang/cargo/issues/10025). RUSTDOCFLAGS: "-D warnings" diff --git a/crates/red_knot_python_semantic/src/semantic_index.rs b/crates/red_knot_python_semantic/src/semantic_index.rs index 54d0ba3b33a4b..333ca35dfa50d 100644 --- a/crates/red_knot_python_semantic/src/semantic_index.rs +++ b/crates/red_knot_python_semantic/src/semantic_index.rs @@ -89,8 +89,6 @@ pub(crate) struct SemanticIndex<'db> { scopes: IndexVec, /// Map expressions to their corresponding scope. - /// We can't use [`ExpressionId`] here, because the challenge is how to get from - /// an [`ast::Expr`] to an [`ExpressionId`] (which requires knowing the scope). scopes_by_expression: FxHashMap, /// Map from a node creating a definition to its definition. @@ -118,7 +116,7 @@ pub(crate) struct SemanticIndex<'db> { impl<'db> SemanticIndex<'db> { /// Returns the symbol table for a specific scope. /// - /// Use the Salsa cached [`symbol_table`] query if you only need the + /// Use the Salsa cached [`symbol_table()`] query if you only need the /// symbol table for a single scope. pub(super) fn symbol_table(&self, scope_id: FileScopeId) -> Arc { self.symbol_tables[scope_id].clone() @@ -126,7 +124,7 @@ impl<'db> SemanticIndex<'db> { /// Returns the use-def map for a specific scope. /// - /// Use the Salsa cached [`use_def_map`] query if you only need the + /// Use the Salsa cached [`use_def_map()`] query if you only need the /// use-def map for a single scope. pub(super) fn use_def_map(&self, scope_id: FileScopeId) -> Arc { self.use_def_maps[scope_id].clone() diff --git a/crates/red_knot_python_semantic/src/semantic_index/ast_ids.rs b/crates/red_knot_python_semantic/src/semantic_index/ast_ids.rs index 1aa0a869f716a..77750b730368f 100644 --- a/crates/red_knot_python_semantic/src/semantic_index/ast_ids.rs +++ b/crates/red_knot_python_semantic/src/semantic_index/ast_ids.rs @@ -26,9 +26,9 @@ use crate::Db; /// ``` #[derive(Debug)] pub(crate) struct AstIds { - /// Maps expressions to their expression id. Uses `NodeKey` because it avoids cloning [`Parsed`]. + /// Maps expressions to their expression id. expressions_map: FxHashMap, - /// Maps expressions which "use" a symbol (that is, [`ExprName`]) to a use id. + /// Maps expressions which "use" a symbol (that is, [`ast::ExprName`]) to a use id. uses_map: FxHashMap, } diff --git a/crates/red_knot_python_semantic/src/types/infer.rs b/crates/red_knot_python_semantic/src/types/infer.rs index 644a15ddd0124..8e2fcfc66771b 100644 --- a/crates/red_knot_python_semantic/src/types/infer.rs +++ b/crates/red_knot_python_semantic/src/types/infer.rs @@ -61,7 +61,7 @@ pub(crate) fn infer_scope_types<'db>(db: &'db dyn Db, scope: ScopeId<'db>) -> Ty TypeInferenceBuilder::new(db, InferenceRegion::Scope(scope), index).finish() } -/// Cycle recovery for [`infer_definition_types`]: for now, just [`Type::Unknown`] +/// Cycle recovery for [`infer_definition_types()`]: for now, just [`Type::Unknown`] /// TODO fixpoint iteration fn infer_definition_types_cycle_recovery<'db>( _db: &'db dyn Db, @@ -923,7 +923,6 @@ impl<'db> TypeInferenceBuilder<'db> { ty } - #[allow(clippy::unused_self)] fn infer_number_literal_expression(&mut self, literal: &ast::ExprNumberLiteral) -> Type<'db> { let ast::ExprNumberLiteral { range: _, value } = literal;