docs: document all public items in rust codebase (#2058)

crates/tinymist-query/src/analysis/completion.rs

@@ -28,7 +28,7 @@ use typst_shim::{syntax::LinkedNodeExt, utils::hash128};
 use unscanny::Scanner;
 
 use crate::adt::interner::Interned;
-use crate::analysis::{BuiltinTy, LocalContext, PathPreference, Ty};
+use crate::analysis::{BuiltinTy, LocalContext, PathKind, Ty};
 use crate::completion::{
     Completion, CompletionCommand, CompletionContextKey, CompletionItem, CompletionKind,
     DEFAULT_POSTFIX_SNIPPET, DEFAULT_PREFIX_SNIPPET, EcoTextEdit, ParsedSnippet, PostfixSnippet,
@@ -632,7 +632,7 @@ impl CompletionPair<'_, '_, '_> {
                     self.package_completions(all_versions);
                     return Some(());
                 } else {
-                    let paths = self.complete_path(&crate::analysis::PathPreference::Source {
+                    let paths = self.complete_path(&crate::analysis::PathKind::Source {
                         allow_package: true,
                     });
                     // todo: remove ctx.completions

crates/tinymist-query/src/analysis/completion/path.rs

@@ -4,7 +4,7 @@ use tinymist_world::vfs::WorkspaceResolver;
 
 use super::*;
 impl CompletionPair<'_, '_, '_> {
-    pub fn complete_path(&mut self, preference: &PathPreference) -> Option<Vec<CompletionItem>> {
+    pub fn complete_path(&mut self, preference: &PathKind) -> Option<Vec<CompletionItem>> {
         let id = self.cursor.source.id();
         if WorkspaceResolver::is_package_file(id) {
             return None;

crates/tinymist-query/src/analysis/global.rs

@@ -33,7 +33,7 @@ use super::{LspQuerySnapshot, TypeEnv};
 use crate::adt::revision::{RevisionLock, RevisionManager, RevisionManagerLike, RevisionSlot};
 use crate::analysis::prelude::*;
 use crate::analysis::{
-    AnalysisStats, BibInfo, CompletionFeat, Definition, PathPreference, QueryStatGuard,
+    AnalysisStats, BibInfo, CompletionFeat, Definition, PathKind, QueryStatGuard,
     SemanticTokenCache, SemanticTokenContext, SemanticTokens, Signature, SignatureTarget, Ty,
     TypeInfo, analyze_signature, bib_info, definition, post_type_check,
 };
@@ -339,16 +339,13 @@ impl LocalContext {
     }
 
     /// Get all the source files in the workspace.
-    pub(crate) fn completion_files(
-        &self,
-        pref: &PathPreference,
-    ) -> impl Iterator<Item = &TypstFileId> {
+    pub(crate) fn completion_files(&self, pref: &PathKind) -> impl Iterator<Item = &TypstFileId> {
         let regexes = pref.ext_matcher();
         self.caches
             .completion_files
             .get_or_init(|| {
                 if let Some(root) = self.world.entry_state().workspace_root() {
-                    scan_workspace_files(&root, PathPreference::Special.ext_matcher(), |path| {
+                    scan_workspace_files(&root, PathKind::Special.ext_matcher(), |path| {
                         WorkspaceResolver::workspace_file(Some(&root), VirtualPath::new(path))
                     })
                 } else {
@@ -368,7 +365,7 @@ impl LocalContext {
     /// Get all the source files in the workspace.
     pub fn source_files(&self) -> &Vec<TypstFileId> {
         self.caches.root_files.get_or_init(|| {
-            self.completion_files(&PathPreference::Source {
+            self.completion_files(&PathKind::Source {
                 allow_package: false,
             })
             .copied()
@@ -391,7 +388,7 @@ impl LocalContext {
     /// Get all depended files in the workspace, inclusively.
     pub fn depended_source_files(&self) -> EcoVec<TypstFileId> {
         let mut ids = self.depended_files();
-        let preference = PathPreference::Source {
+        let preference = PathKind::Source {
             allow_package: false,
         };
         ids.retain(|id| preference.is_match(id.vpath().as_rooted_path()));

crates/tinymist-query/src/analysis/post_tyck.rs

@@ -311,11 +311,11 @@ impl<'a> PostTypeChecker<'a> {
                 crate::log_debug_ct!("post check target iterated: {:?}", resp.bounds);
                 Some(resp.finalize())
             }
-            SyntaxContext::ImportPath(..) | SyntaxContext::IncludePath(..) => Some(Ty::Builtin(
-                BuiltinTy::Path(crate::ty::PathPreference::Source {
+            SyntaxContext::ImportPath(..) | SyntaxContext::IncludePath(..) => {
+                Some(Ty::Builtin(BuiltinTy::Path(crate::ty::PathKind::Source {
                     allow_package: true,
-                }),
-            )),
+                })))
+            }
             SyntaxContext::VarAccess(VarClass::Ident(node))
             | SyntaxContext::VarAccess(VarClass::FieldAccess(node))
             | SyntaxContext::VarAccess(VarClass::DotAccess(node))

crates/tinymist-query/src/hover.rs

@@ -248,7 +248,7 @@ impl HoverWorker<'_> {
                     args: vec![JsonValue::String(target.to_string())],
                 }],
             });
-            if let Some(kind) = PathPreference::from_ext(target.path()) {
+            if let Some(kind) = PathKind::from_ext(target.path()) {
                 self.def.push(format!("A `{kind:?}` file."));
             }
         }

crates/tinymist-query/src/lib.rs

@@ -127,7 +127,6 @@ pub trait StatefulRequest {
     fn request(self, ctx: &mut LocalContext, graph: LspComputeGraph) -> Option<Self::Response>;
 }
 
-#[allow(missing_docs)]
 mod polymorphic {
     use completion::CompletionList;
     use lsp_types::TextEdit;
@@ -138,6 +137,7 @@ mod polymorphic {
     use super::prelude::*;
     use super::*;
 
+    /// A request to run an export task.
     #[derive(Debug, Clone)]
     pub struct OnExportRequest {
         /// The path of the document to export.
@@ -148,68 +148,111 @@ mod polymorphic {
         pub open: bool,
     }
 
+    /// A request to format the document.
     #[derive(Debug, Clone)]
     pub struct FormattingRequest {
         /// The path of the document to get semantic tokens for.
         pub path: PathBuf,
     }
 
+    /// A request to get the server info.
     #[derive(Debug, Clone)]
     pub struct ServerInfoRequest {}
 
+    /// The response to the server info request.
     #[derive(Debug, Clone, Serialize, Deserialize)]
     #[serde(rename_all = "camelCase")]
     pub struct ServerInfoResponse {
+        /// The root path of the server.
         pub root: Option<PathBuf>,
+        /// The font paths of the server.
         pub font_paths: Vec<PathBuf>,
+        /// The inputs of the server.
         pub inputs: Dict,
+        /// The statistics of the server.
         pub stats: HashMap<String, String>,
     }
 
+    /// The feature of the fold request.
     #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
     pub enum FoldRequestFeature {
+        /// Serves the request with the first pinned entry.
         PinnedFirst,
+        /// Makes the items unique.
         Unique,
+        /// Merges the items.
         Mergeable,
+        /// Makes the items unique without context.
         ContextFreeUnique,
     }
 
+    /// The analysis request.
     #[derive(Debug, Clone, strum::IntoStaticStr)]
     pub enum CompilerQueryRequest {
+        /// A request to run an export task.
         OnExport(OnExportRequest),
+        /// A request to get the hover information.
         Hover(HoverRequest),
+        /// A request to go to the definition.
         GotoDefinition(GotoDefinitionRequest),
+        /// A request to go to the declaration.
         GotoDeclaration(GotoDeclarationRequest),
+        /// A request to get the references.
         References(ReferencesRequest),
+        /// A request to get the inlay hints.
         InlayHint(InlayHintRequest),
+        /// A request to get the document colors.
         DocumentColor(DocumentColorRequest),
+        /// A request to get the document links.
         DocumentLink(DocumentLinkRequest),
+        /// A request to get the document highlights.
         DocumentHighlight(DocumentHighlightRequest),
+        /// A request to get the color presentations.
         ColorPresentation(ColorPresentationRequest),
+        /// A request to get the code actions.
         CodeAction(CodeActionRequest),
+        /// A request to get the code lenses.
         CodeLens(CodeLensRequest),
+        /// A request to get the completions.
         Completion(CompletionRequest),
+        /// A request to get the signature helps.
         SignatureHelp(SignatureHelpRequest),
+        /// A request to rename.
         Rename(RenameRequest),
+        /// A request to determine the files to be renamed.
         WillRenameFiles(WillRenameFilesRequest),
+        /// A request to prepare the rename.
         PrepareRename(PrepareRenameRequest),
+        /// A request to get the document symbols.
         DocumentSymbol(DocumentSymbolRequest),
+        /// A request to get the symbols.
         Symbol(SymbolRequest),
+        /// A request to get the semantic tokens full.
         SemanticTokensFull(SemanticTokensFullRequest),
+        /// A request to get the semantic tokens delta.
         SemanticTokensDelta(SemanticTokensDeltaRequest),
+        /// A request to format the document.
         Formatting(FormattingRequest),
+        /// A request to get the folding ranges.
         FoldingRange(FoldingRangeRequest),
+        /// A request to get the selection ranges.
         SelectionRange(SelectionRangeRequest),
+        /// A request to interact with the code context.
         InteractCodeContext(InteractCodeContextRequest),
 
+        /// A request to get extra text edits on enter.
         OnEnter(OnEnterRequest),
 
+        /// A request to get the document metrics.
         DocumentMetrics(DocumentMetricsRequest),
+        /// A request to get the workspace labels.
         WorkspaceLabel(WorkspaceLabelRequest),
+        /// A request to get the server info.
         ServerInfo(ServerInfoRequest),
     }
 
     impl CompilerQueryRequest {
+        /// Gets the feature of the fold request.
         pub fn fold_feature(&self) -> FoldRequestFeature {
             use FoldRequestFeature::*;
             match self {
@@ -247,6 +290,7 @@ mod polymorphic {
             }
         }
 
+        /// Gets the associated path of the request.
         pub fn associated_path(&self) -> Option<&Path> {
             Some(match self {
                 Self::OnExport(..) => return None,
@@ -284,39 +328,69 @@ mod polymorphic {
         }
     }
 
+    /// The response to the compiler query request.
     #[derive(Debug, Clone, Serialize, Deserialize)]
     #[serde(untagged)]
     pub enum CompilerQueryResponse {
+        /// The response to the on export request.
         OnExport(Option<PathBuf>),
+        /// The response to the hover request.
         Hover(Option<Hover>),
+        /// The response to the goto definition request.
         GotoDefinition(Option<GotoDefinitionResponse>),
+        /// The response to the goto declaration request.
         GotoDeclaration(Option<GotoDeclarationResponse>),
+        /// The response to the references request.
         References(Option<Vec<LspLocation>>),
+        /// The response to the inlay hint request.
         InlayHint(Option<Vec<InlayHint>>),
+        /// The response to the document color request.
         DocumentColor(Option<Vec<ColorInformation>>),
+        /// The response to the document link request.
         DocumentLink(Option<Vec<DocumentLink>>),
+        /// The response to the document highlight request.
         DocumentHighlight(Option<Vec<DocumentHighlight>>),
+        /// The response to the color presentation request.
         ColorPresentation(Option<Vec<ColorPresentation>>),
+        /// The response to the code action request.
         CodeAction(Option<Vec<CodeAction>>),
+        /// The response to the code lens request.
         CodeLens(Option<Vec<CodeLens>>),
+        /// The response to the completion request.
         Completion(Option<CompletionList>),
+        /// The response to the signature help request.
         SignatureHelp(Option<SignatureHelp>),
+        /// The response to the prepare rename request.
         PrepareRename(Option<PrepareRenameResponse>),
+        /// The response to the rename request.
         Rename(Option<WorkspaceEdit>),
+        /// The response to the will rename files request.
         WillRenameFiles(Option<WorkspaceEdit>),
+        /// The response to the document symbol request.
         DocumentSymbol(Option<DocumentSymbolResponse>),
+        /// The response to the symbol request.
         Symbol(Option<Vec<SymbolInformation>>),
+        /// The response to the workspace label request.
         WorkspaceLabel(Option<Vec<SymbolInformation>>),
+        /// The response to the semantic tokens full request.
         SemanticTokensFull(Option<SemanticTokensResult>),
+        /// The response to the semantic tokens delta request.
         SemanticTokensDelta(Option<SemanticTokensFullDeltaResult>),
+        /// The response to the formatting request.
         Formatting(Option<Vec<TextEdit>>),
+        /// The response to the folding range request.
         FoldingRange(Option<Vec<FoldingRange>>),
+        /// The response to the selection range request.
         SelectionRange(Option<Vec<SelectionRange>>),
+        /// The response to the interact code context request.
         InteractCodeContext(Option<Vec<Option<InteractCodeContextResponse>>>),
 
+        /// The response to the on enter request.
         OnEnter(Option<Vec<TextEdit>>),
 
+        /// The response to the document metrics request.
         DocumentMetrics(Option<DocumentMetricsResponse>),
+        /// The response to the server info request.
         ServerInfo(Option<HashMap<String, ServerInfoResponse>>),
     }
 }

crates/tinymist-query/src/prelude.rs

@@ -36,5 +36,5 @@ pub use crate::lsp_typst_boundary::{
     to_typst_range,
 };
 pub use crate::syntax::{Decl, DefKind, classify_syntax};
-pub(crate) use crate::ty::PathPreference;
+pub(crate) use crate::ty::PathKind;
 pub use crate::{SemanticRequest, StatefulRequest};

crates/tinymist-query/src/syntax/expr.rs

@@ -1,5 +1,3 @@
-#![allow(missing_docs)]
-
 use std::ops::DerefMut;
 
 use parking_lot::Mutex;

crates/tinymist-query/src/syntax/index.rs

@@ -5,13 +5,18 @@ use tinymist_world::package::PackageSpec;
 
 use crate::{adt::interner::Interned, prelude::*};
 
+/// The information for the index.
 #[derive(Default)]
 pub struct IndexInfo {
+    /// The paths in the source.
     pub(crate) paths: FxHashSet<Interned<str>>,
+    /// The packages in the source.
     pub(crate) packages: FxHashSet<PackageSpec>,
+    /// The identifiers in the source.
     pub(crate) identifiers: FxHashSet<Interned<str>>,
 }
 
+/// Gets the index information for the source.
 #[typst_macros::time(span = src.root().span())]
 #[comemo::memoize]
 pub fn get_index_info(src: &Source) -> Arc<IndexInfo> {
@@ -23,11 +28,13 @@ pub fn get_index_info(src: &Source) -> Arc<IndexInfo> {
     Arc::new(worker.info)
 }
 
+/// The worker for the index.
 struct IndexWorker {
     info: IndexInfo,
 }
 
 impl IndexWorker {
+    /// Visits the node.
     fn visit(&mut self, node: &SyntaxNode) {
         match node.cast::<ast::Expr>() {
             Some(ast::Expr::Str(path_str)) => {

crates/tinymist-query/src/syntax/lexical_hierarchy.rs

@@ -47,49 +47,65 @@ pub(crate) fn get_lexical_hierarchy(
     res.map(|_| worker.stack.pop().unwrap().1)
 }
 
+/// The kind of a variable.
 #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
 pub enum LexicalVarKind {
+    /// A value reference.
     /// `#foo`
     ///   ^^^
     ValRef,
+    /// A label reference.
     /// `@foo`
     ///   ^^^
     LabelRef,
+    /// A label.
     /// `<foo>`
     ///   ^^^
     Label,
+    /// A bib key.
     /// `x:`
     ///  ^^
     BibKey,
+    /// A variable.
     /// `let foo`
     ///      ^^^
     Variable,
+    /// A function.
     /// `let foo()`
     ///      ^^^
     Function,
 }
 
+/// The kind of a lexical hierarchy recogized by the analyzers.
 #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
 pub enum LexicalKind {
+    /// A heading.
     Heading(i16),
+    /// A variable.
     Var(LexicalVarKind),
+    /// A block.
     Block,
+    /// A comment group.
     CommentGroup,
 }
 
 impl LexicalKind {
+    /// Creates a label.
     const fn label() -> LexicalKind {
         LexicalKind::Var(LexicalVarKind::Label)
     }
 
+    /// Creates a function.
     const fn function() -> LexicalKind {
         LexicalKind::Var(LexicalVarKind::Function)
     }
 
+    /// Creates a variable.
     const fn variable() -> LexicalKind {
         LexicalKind::Var(LexicalVarKind::Variable)
     }
 
+    /// Checks if the kind is a valid LSP symbol.
     pub fn is_valid_lsp_symbol(&self) -> bool {
         !matches!(self, LexicalKind::Block | LexicalKind::CommentGroup)
     }

crates/tinymist-query/src/syntax/mod.rs

@@ -2,8 +2,6 @@
 //!
 //! This module must hide all **AST details** from the rest of the codebase.
 
-#![allow(missing_docs)]
-
 pub(crate) mod docs;
 pub(crate) mod expr;
 pub(crate) mod index;