This PR adds comprehensive documentation for all public items in
`crates/tinymist-query/src/syntax/expr.rs` following Rust documentation
conventions.
## Changes Made
The following public items now have proper documentation comments:
- **`ExprRoute`** type alias - Documents its purpose as a mapping
structure for file identifiers to lexical scopes during expression
analysis routing
- **`expr_of`** function - Describes its role in analyzing expressions
within source files and producing expression information including
resolves, imports, docstrings, and lexical scoping data
- **`ExprWorker`** struct - Explains its functionality as a worker for
processing expressions during source file analysis, handling expression
checking, scope management, symbol resolution, and docstring collection
## Documentation Style
All documentation follows Rust conventions by:
- Using third person singular verbs
- Focusing on the purpose and functionality rather than implementation
details
- Providing clear, concise descriptions of what each item does
The code has been formatted with `cargo fmt` and compiles successfully
after the changes.
Fixes#2048.
<!-- START COPILOT CODING AGENT TIPS -->
---
💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.
---------
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)]
|
```
It provides a `package-doc.json` and HTML is rendered using a
`package-doc` function.
```typ
#let package-doc(info, path: none) [
#metadata((
// more sub paths
)) <static-paths>
#render-page(info, path) // the content of $path/.html
]
#package-doc(json("package-doc.json"))
```
When `f` is a scope with at least one member:
- completes `#f` as `#f()` if `f` will never be a type or element
(merely a function).
- Otherwise, completes `#f` as `#f` and adds a variant `#f.paren`
completed as `#f(|)` or `#f()|`
This excepts for the following cases:
- When the surrounding syntax doesn't like parentheses (for example,
function fields)
> Complete the field name along with its value. Notes:
> No parentheses since function fields cannot currently be called
> with method syntax;
- When the surrounding syntax requires parentheses, for example set
rules, e.g. `#set r|` is completed as `#set raw(|)`.
When passing configuration items with null values, the default
configurations are used. Note: I don't ensure this to be always true,
some configuration items may have different non-default behaviors when
accepting a null value now or in future. The `deserialize_null_default`
is taken from https://github.com/serde-rs/serde/issues/1098.
Configuration parsing changes:
+ some configurations only accepting boolean now coerce null to `false`
(default).
+ some configurations only accepting an object now coerce null to
default.
+ The `tinymist.preview.invertColors` now now coerces null to `"never"`
(default).
* feat: print doc errors
* fix: test errors on windows
* fix: tests on windows again
* fix: tests on windows again 2
* Revert "fix: tests on windows again 2"
This reverts commit 63973dcc1f.
* fix: tests on windows again 3
* fix(test): running test as root
The dummy root path /root conflicts with root user's home directory on Linux and redacts incorrectly. Our downstream CI environment builds tinymist in docker as root and encounters the problem. Change the path to `/dummy-root` fixes it. To ensure consistency, other similar occurences are also prefixed with `dummy-`.
* dev: deduplicate a bit
---------
Co-authored-by: Myriad-Dreamin <camiyoru@gmail.com>
* fix: readme generation
* feat: markdown-aware export
* feat: add ieee example
* fix: fix wrong behavior of list parsing and <div> elem parsing
* test: update snapshot
Co-authored-by: Hong Jiarong <me@jrhim.com>
* fix: clippy warnings
* fix: handle br tag as hard break in HTML parsing (#1769)
* fix: handle br tag as hard break in HTML parsing
* Revert "svg gen"
This reverts commit 1ff4c0af33c209a9f653c879f2f7d504bad1ff32.
---------
Co-authored-by: Myriad-Dreamin <camiyoru@gmail.com>
* feat: some md-specific impl
* test: bad changes
---------
Co-authored-by: Hong Jiarong <me@jrhim.com>
* fix: block math align center
* fix: block math align center (#1764)
* fix: process block children
* test: update snapshot
---------
Co-authored-by: Hong Jiarong <me@jrhim.com>
* Revert "test: update bad snapshot"
This reverts commit 7ba7eb1793.
* fix: update cmark-writer to version 0.6.3 and adjust related snapshots (#1721)
* fix: annotate_docs_error and list level, but bring up 2 new errors.. (#1723)
* fix: adjust list level handling in ListParser during conversion
* fix: manually eval instead of include
* fix: annotate_docs_error, but bring up 2 new errors..
* fix: spaces
* fix: example
---------
Co-authored-by: Myriad-Dreamin <camiyoru@gmail.com>
* fix: no html
* test: update snapshot
---------
Co-authored-by: Hong Jiarong <me@jrhim.com>
* 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>
