From 188b0f96f98feaa0771f941343887c46113c8ced Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 22 May 2021 16:53:47 +0300 Subject: [PATCH] Add more docs --- crates/hir/src/db.rs | 7 +++++-- crates/hir/src/diagnostics.rs | 6 +++++- crates/ide/src/display/navigation_target.rs | 2 +- crates/ide/src/folding_ranges.rs | 6 ++++-- crates/ide_assists/src/assist_context.rs | 2 +- crates/ide_assists/src/path_transform.rs | 3 ++- crates/profile/src/lib.rs | 2 +- crates/profile/src/memory_usage.rs | 6 ++++-- crates/profile/src/stop_watch.rs | 4 ++-- crates/project_model/src/cargo_workspace.rs | 7 +++---- crates/project_model/src/lib.rs | 17 ++++++++++++++++- crates/project_model/src/project_json.rs | 7 ++++++- crates/syntax/fuzz/fuzz_targets/parser.rs | 2 +- crates/syntax/fuzz/fuzz_targets/reparse.rs | 2 +- crates/syntax/src/algo.rs | 2 +- crates/syntax/src/fuzz.rs | 4 +++- crates/syntax/src/parsing/text_tree_sink.rs | 2 +- crates/syntax/src/ptr.rs | 11 ++++++++++- crates/tt/src/buffer.rs | 7 ++++--- xtask/src/tidy.rs | 13 +------------ 20 files changed, 72 insertions(+), 40 deletions(-) diff --git a/crates/hir/src/db.rs b/crates/hir/src/db.rs index ffc8155b94..19898f6839 100644 --- a/crates/hir/src/db.rs +++ b/crates/hir/src/db.rs @@ -1,5 +1,8 @@ -//! FIXME: write short doc here - +//! Re-exports various subcrates databases so that the calling code can depend +//! only on `hir`. This breaks abstraction boundary a bit, it would be cool if +//! we didn't do that. +//! +//! But we need this for at least LRU caching at the query level. pub use hir_def::db::*; pub use hir_expand::db::{ AstDatabase, AstDatabaseStorage, AstIdMapQuery, HygieneFrameQuery, InternMacroQuery, diff --git a/crates/hir/src/diagnostics.rs b/crates/hir/src/diagnostics.rs index b1ebba5164..414c3f35ee 100644 --- a/crates/hir/src/diagnostics.rs +++ b/crates/hir/src/diagnostics.rs @@ -1,4 +1,8 @@ -//! FIXME: write short doc here +//! Re-export diagnostics such that clients of `hir` don't have to depend on +//! low-level crates. +//! +//! This probably isn't the best way to do this -- ideally, diagnistics should +//! be expressed in terms of hir types themselves. pub use hir_def::diagnostics::{ InactiveCode, UnresolvedMacroCall, UnresolvedModule, UnresolvedProcMacro, }; diff --git a/crates/ide/src/display/navigation_target.rs b/crates/ide/src/display/navigation_target.rs index 2079c22a37..b75ec411cf 100644 --- a/crates/ide/src/display/navigation_target.rs +++ b/crates/ide/src/display/navigation_target.rs @@ -1,4 +1,4 @@ -//! FIXME: write short doc here +//! See [`NavigationTarget`]. use std::fmt; diff --git a/crates/ide/src/folding_ranges.rs b/crates/ide/src/folding_ranges.rs index a039887783..b893c1c541 100755 --- a/crates/ide/src/folding_ranges.rs +++ b/crates/ide/src/folding_ranges.rs @@ -1,5 +1,3 @@ -//! FIXME: write short doc here - use rustc_hash::FxHashSet; use syntax::{ @@ -29,6 +27,10 @@ pub struct Fold { pub kind: FoldKind, } +// Feature: Folding +// +// Defines folding regions for curly braced blocks, runs of consecutive import +// statements, and `region` / `endregion` comment markers. pub(crate) fn folding_ranges(file: &SourceFile) -> Vec { let mut res = vec![]; let mut visited_comments = FxHashSet::default(); diff --git a/crates/ide_assists/src/assist_context.rs b/crates/ide_assists/src/assist_context.rs index 20754a02ad..8fc40f9bdf 100644 --- a/crates/ide_assists/src/assist_context.rs +++ b/crates/ide_assists/src/assist_context.rs @@ -1,4 +1,4 @@ -//! See `AssistContext` +//! See [`AssistContext`]. use std::mem; diff --git a/crates/ide_assists/src/path_transform.rs b/crates/ide_assists/src/path_transform.rs index 6ec318c4ce..48a7fa06a2 100644 --- a/crates/ide_assists/src/path_transform.rs +++ b/crates/ide_assists/src/path_transform.rs @@ -1,4 +1,5 @@ -//! See `PathTransform` +//! See [`PathTransform`]. + use hir::{HirDisplay, SemanticsScope}; use ide_db::helpers::mod_path_to_ast; use rustc_hash::FxHashMap; diff --git a/crates/profile/src/lib.rs b/crates/profile/src/lib.rs index a31fb8f439..7cd01a7dfc 100644 --- a/crates/profile/src/lib.rs +++ b/crates/profile/src/lib.rs @@ -124,5 +124,5 @@ impl Drop for CpuSpan { } pub fn memory_usage() -> MemoryUsage { - MemoryUsage::current() + MemoryUsage::now() } diff --git a/crates/profile/src/memory_usage.rs b/crates/profile/src/memory_usage.rs index cb4e544477..2917ded60f 100644 --- a/crates/profile/src/memory_usage.rs +++ b/crates/profile/src/memory_usage.rs @@ -1,4 +1,6 @@ -//! FIXME: write short doc here +//! Like [`std::time::Instant`], but for memory. +//! +//! Measures the total size of all currently allocated objects. use std::fmt; use cfg_if::cfg_if; @@ -22,7 +24,7 @@ impl std::ops::Sub for MemoryUsage { } impl MemoryUsage { - pub fn current() -> MemoryUsage { + pub fn now() -> MemoryUsage { cfg_if! { if #[cfg(all(feature = "jemalloc", not(target_env = "msvc")))] { jemalloc_ctl::epoch::advance().unwrap(); diff --git a/crates/profile/src/stop_watch.rs b/crates/profile/src/stop_watch.rs index cb6915d458..112d03a9c7 100644 --- a/crates/profile/src/stop_watch.rs +++ b/crates/profile/src/stop_watch.rs @@ -44,7 +44,7 @@ impl StopWatch { } pub fn memory(mut self, yes: bool) -> StopWatch { if yes { - self.memory = Some(MemoryUsage::current()); + self.memory = Some(MemoryUsage::now()); } self } @@ -58,7 +58,7 @@ impl StopWatch { #[cfg(not(target_os = "linux"))] let instructions = None; - let memory = self.memory.map(|it| MemoryUsage::current() - it); + let memory = self.memory.map(|it| MemoryUsage::now() - it); StopWatchSpan { time, instructions, memory } } } diff --git a/crates/project_model/src/cargo_workspace.rs b/crates/project_model/src/cargo_workspace.rs index 4a4996cf4d..ad705c7527 100644 --- a/crates/project_model/src/cargo_workspace.rs +++ b/crates/project_model/src/cargo_workspace.rs @@ -1,4 +1,4 @@ -//! FIXME: write short doc here +//! See [`CargoWorkspace`]. use std::path::PathBuf; use std::{convert::TryInto, ops, process::Command, sync::Arc}; @@ -12,10 +12,9 @@ use rustc_hash::FxHashMap; use serde::Deserialize; use serde_json::from_value; -use crate::build_data::BuildDataConfig; -use crate::utf8_stdout; +use crate::{build_data::BuildDataConfig, utf8_stdout}; -/// `CargoWorkspace` represents the logical structure of, well, a Cargo +/// [`CargoWorkspace`] represents the logical structure of, well, a Cargo /// workspace. It pretty closely mirrors `cargo metadata` output. /// /// Note that internally, rust analyzer uses a different structure: diff --git a/crates/project_model/src/lib.rs b/crates/project_model/src/lib.rs index a5b35ed953..8c6cf94c24 100644 --- a/crates/project_model/src/lib.rs +++ b/crates/project_model/src/lib.rs @@ -1,4 +1,19 @@ -//! FIXME: write short doc here +//! In rust-analyzer, we maintain a strict separation between pure abstract +//! semantic project model and a concrete model of a particular build system. +//! +//! Pure model is represented by the [`base_db::CrateGraph`] from another crate. +//! +//! In this crate, we are conserned with "real world" project models. +//! +//! Specifically, here we have a representation for a Cargo project +//! ([`CargoWorkspace`]) and for manually specified layout ([`ProjectJson`]). +//! +//! Roughly, the things we do here are: +//! +//! * Project discovery (where's the relevant Cargo.toml for the current dir). +//! * Custom build steps (`build.rs` code generation and compilation of +//! procedural macros). +//! * Lowering of concrete model to a [`base_db::CrateGraph`] mod cargo_workspace; mod cfg_flag; diff --git a/crates/project_model/src/project_json.rs b/crates/project_model/src/project_json.rs index 41a2ac03e0..e8f1aca61b 100644 --- a/crates/project_model/src/project_json.rs +++ b/crates/project_model/src/project_json.rs @@ -1,4 +1,9 @@ -//! FIXME: write short doc here +//! `rust-project.json` file format. +//! +//! This format is spiritually a serialization of [`base_db::CrateGraph`]. The +//! idea here is that people who do not use Cargo, can instead teach their build +//! system to generate `rust-project.json` which can be ingested by +//! rust-analyzer. use std::path::PathBuf; diff --git a/crates/syntax/fuzz/fuzz_targets/parser.rs b/crates/syntax/fuzz/fuzz_targets/parser.rs index 386768343b..f80e130021 100644 --- a/crates/syntax/fuzz/fuzz_targets/parser.rs +++ b/crates/syntax/fuzz/fuzz_targets/parser.rs @@ -1,4 +1,4 @@ -//! FIXME: write short doc here +//! Fuzzing for from-scratch parsing. #![no_main] use libfuzzer_sys::fuzz_target; diff --git a/crates/syntax/fuzz/fuzz_targets/reparse.rs b/crates/syntax/fuzz/fuzz_targets/reparse.rs index 5ac99fdafd..f865ce8d67 100644 --- a/crates/syntax/fuzz/fuzz_targets/reparse.rs +++ b/crates/syntax/fuzz/fuzz_targets/reparse.rs @@ -1,4 +1,4 @@ -//! FIXME: write short doc here +//! Fuzzing for incremental parsing. #![no_main] use libfuzzer_sys::fuzz_target; diff --git a/crates/syntax/src/algo.rs b/crates/syntax/src/algo.rs index 241713c48e..8d7a77b507 100644 --- a/crates/syntax/src/algo.rs +++ b/crates/syntax/src/algo.rs @@ -1,4 +1,4 @@ -//! FIXME: write short doc here +//! Collection of assorted algorithms for syntax trees. use std::{hash::BuildHasherDefault, ops::RangeInclusive}; diff --git a/crates/syntax/src/fuzz.rs b/crates/syntax/src/fuzz.rs index aa84239d2f..256999fe09 100644 --- a/crates/syntax/src/fuzz.rs +++ b/crates/syntax/src/fuzz.rs @@ -1,4 +1,6 @@ -//! FIXME: write short doc here +//! Some infrastructure for fuzzy testing. +//! +//! We don't normally run fuzzying, so this is hopelessly bitrotten :( use std::{ convert::TryInto, diff --git a/crates/syntax/src/parsing/text_tree_sink.rs b/crates/syntax/src/parsing/text_tree_sink.rs index d63ec080b4..25bfd41a16 100644 --- a/crates/syntax/src/parsing/text_tree_sink.rs +++ b/crates/syntax/src/parsing/text_tree_sink.rs @@ -1,4 +1,4 @@ -//! FIXME: write short doc here +//! See [`TextTreeSink`]. use std::mem; diff --git a/crates/syntax/src/ptr.rs b/crates/syntax/src/ptr.rs index d3fb7a5d98..195d2251b1 100644 --- a/crates/syntax/src/ptr.rs +++ b/crates/syntax/src/ptr.rs @@ -1,4 +1,13 @@ -//! FIXME: write short doc here +//! In rust-analyzer, syntax trees are transient objects. +//! +//! That means that we create trees when we need them, and tear them down to +//! save memory. In this architecture, hanging on to a particular syntax node +//! for a long time is ill-advisable, as that keeps the whole tree resident. +//! +//! Instead, we provide a [`SyntaxNodePtr`] type, which stores information about +//! *location* of a particular syntax node in a tree. Its a small type which can +//! be cheaply stored, and which can be resolved to a real [`SyntaxNode`] when +//! necessary. use std::{ hash::{Hash, Hasher}, diff --git a/crates/tt/src/buffer.rs b/crates/tt/src/buffer.rs index 3606c887dc..e0021039ae 100644 --- a/crates/tt/src/buffer.rs +++ b/crates/tt/src/buffer.rs @@ -1,5 +1,6 @@ -//! FIXME: write short doc here - +//! Stateful iteration over token trees. +//! +//! We use this as the source of tokens for parser. use crate::{Leaf, Subtree, TokenTree}; #[derive(Copy, Clone, Debug, Eq, PartialEq)] @@ -104,7 +105,7 @@ impl<'t> TokenBuffer<'t> { /// Creates a cursor referencing the first token in the buffer and able to /// traverse until the end of the buffer. - pub fn begin(&self) -> Cursor { + pub fn begin(&self) -> Cursor<'_> { Cursor::create(self, EntryPtr(EntryId(0), 0)) } diff --git a/xtask/src/tidy.rs b/xtask/src/tidy.rs index 6c55823eb0..e31cc2a673 100644 --- a/xtask/src/tidy.rs +++ b/xtask/src/tidy.rs @@ -392,18 +392,7 @@ impl TidyDocs { ) } - let poorly_documented = [ - "hir", - "hir_expand", - "ide", - "mbe", - "parser", - "profile", - "project_model", - "syntax", - "tt", - "hir_ty", - ]; + let poorly_documented = ["hir_expand", "mbe", "parser", "hir_ty"]; let mut has_fixmes = poorly_documented.iter().map(|it| (*it, false)).collect::>();