This PR adds comprehensive documentation comments to all public items in
`crates/tinymist-analysis/src/syntax/def.rs`. The file contained
numerous public structs, enums, functions, and fields that lacked
documentation, making it difficult for contributors to understand the
purpose and usage of these types in the syntax analysis system.
## Changes Made
- **Public Types**: Added documentation to 40+ public types including
core expression types (`ExprInfo`, `ExprInfoRepr`, `Expr`), declaration
types (`Decl`, `DefKind`), and expression-specific structs
- **Public Functions**: Added documentation to 60+ public functions
including:
- Constructor methods for all declaration types (`Decl::func`,
`Decl::var`, etc.)
- Utility methods across all major types (`get_def`, `is_exported`,
`span`, etc.)
- Expression and operation constructors (`SelectExpr::new`,
`UnInst::new`, etc.)
- **Public Fields**: Added documentation to all public fields in 35+
structs, explaining their purpose and usage context
- **Type Aliases**: Documented utility types like `LexicalScope`,
`DeclExpr`, `ExportMap`
All documentation follows the existing codebase style using triple-slash
comments (`///`) and focuses on explaining the purpose, usage context,
and behavior of each item within the syntax analysis pipeline.
## Verification
- Code formatting applied using `cargo fmt`
- No functional changes made - purely documentation additions
- All public API items in the file now have appropriate documentation
This significantly improves the developer experience for anyone working
with the syntax analysis components of tinymist.
Fixes#2023.
<!-- START COPILOT CODING AGENT TIPS -->
---
✨ Let Copilot coding agent [set things up for
you](https://github.com/Myriad-Dreamin/tinymist/issues/new?title=✨Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Myriad-Dreamin <35292584+Myriad-Dreamin@users.noreply.github.com>
Co-authored-by: Myriad-Dreamin <camiyoru@gmail.com>
using clippy 0.1.91 (898aff704d 2025-08-14), but some warnings already
exist in the latest stable version
mostly about elided lifetime and if-chain
only remaining warnings:
```
warning: struct `HashRepr` is never constructed
--> crates\tinymist-query\src\tests.rs:462:12
|
462 | pub struct HashRepr<T>(pub T);
| ^^^^^^^^
|
= note: `#[warn(dead_code)]` on by default
warning: a method with this name may be added to the standard library in the future
--> crates\tinymist\src\actor\editor.rs:103:30
|
103 | ... .map_or_default(|fid| unix_slash(fid.vpath().as_rooted_path()));
| ^^^^^^^^^^^^^^
|
= warning: once this associated item is added to the standard library, the ambiguity may cause an error or change in behavior!
= note: for more information, see issue #48919 <https://github.com/rust-lang/rust/issues/48919>
= help: call with fully qualified syntax `typst::typst_utils::OptionExt::map_or_default(...)` to keep using the current method
= note: `#[warn(unstable_name_collisions)]` on by default
help: add `#![feature(result_option_map_or_default)]` to the crate attributes to enable `std::option::Option::<T>::map_or_default`
--> crates\tinymist\src\lib.rs:3:1
|
3 + #![feature(result_option_map_or_default)]
|
```
* dev: init markdown file
* dev: typlite element derive
* feat: pass tests
refactor lib.rs to separated files (#1692)
feat(typlite): Docx export and export markdown in cmark-writer (#1698)
* feat: docx export support
* refactor: simplify DocxConverter structure and improve content handling
* tests: add binary insta for docx
* feat: add MathBlock style and improve frame rendering in DocxConverter
* fix: enhance paragraph creation(silly method)
* fix: enhance math equation rendering
* use md5 instead of docx binary
* feat: enhance list numbering and paragraph handling in DocxConverter
* feat: add all_elements test
* refactor
* reimpl md export in cmark-writer
* feat: add support for highlight tag in MarkdownConverter
* feat: refactor LaTeXConverter to improve element processing and add new methods
* fmt
* Refactor DOCX converter to improve list handling and document structure
- Introduced separate methods for creating ordered and unordered list numbering.
- Enhanced list management by tracking next numbering IDs.
- Consolidated paragraph and run management within the DocxConverter.
- Improved image processing with better error handling and placeholder support.
- Streamlined the handling of various HTML elements, including headings, lists, and images.
- Added functionality for processing captions and preformatted blocks.
- Updated methods for processing inline styles and links.
* feat: update cmark-writer to version 0.2.0
* feat: refactor code block handling in DOCX converter for improved readability
* refactor: refactor DOCX converter to enhance document structure
* refactor docx to separated files
* update instas
* fmt
* chore: update cmark-writer version to 0.3.0
* fix: ol custom value
* feat: table and grid processing
* use cmark-writer's ast node for consistency
* fix: update snapshot hashes for document generation tests
* fix: add preamble
* update snapshot hashes
* refactor DOCX conversion: Split writer functionality into separate module, enhance image processing, and clean up utility functions
* update comments in LaTeX and Markdown converters for clarity and consistency
* fmt
* delete utils
* feat: support figure node by custom node in cmark-writer
* fix
* fix: frame
* feat: enhance table conversion logic in MarkdownConverter
* refactor: simplify FigureNode implementation by removing CustomNode trait
* chore: update cmark-writer to version 0.5.0
* fix: update figure and raw inline snapshots for consistency
* fix: update snapshot hashes and correct caption reference in markdown.typ
* refactor proj structure
* feat: update CompileArgs to support multiple output files and remove debug option
* docs: update README to clarify usage of multiple output formats and comment out feature section
* remove DocxConverter module
* feat: impl assets-path feature and add ExternalFrameNode for handling external frames and update writers to support it
* feat: enhance HTML element conversion to include attributes and children handling
* feat: update cmark-writer to 0.6.1 and refactor related code
* fix: update snapshots for figure caption, list, outline, and docx generation
* feat: refactor HTML element conversion to use create_html_element method and enhance table processing
* fix
* feat: add HighlightNode for highlighted text and integrate with HTML to AST parser and LaTeX writer
* refactoor
* update tests
Co-Authored-By: Hong Jiarong <me@jrhim.com>
* feat: revert latex/docx conversions
* fix: warnings
* bad: convert docs
* build: remove other cargo deps
* build: update cargo.lock
* test: update snapshot
* chore: remove useless parser trait
* feat: annotate v1
* feat: annotate v2
* test: update snapshot
* question: is it a bug?
* test: update bad snapshot
---------
Co-authored-by: Hong Jiarong <me@jrhim.com>
* feat: add path conversion actions for absolute and relative paths in special function call
* feat: implement matchers
* docs: edit comment
* fix: path on windows
* feat: add a comment
* dev: edit a bit
* dev: use `resolved`
* refactor: simplify path rewriting logic using `diff`
* feat: add absolute path import fixture
* fix: update path check for absolute paths to use `starts_with` to work with windows
* feat: add path expression import fixture
---------
Co-authored-by: Myriad-Dreamin <camiyoru@gmail.com>
