- Removed references to 'LspFileSystem' (now WorkspaceFileSystem)
- Removed verbose 'overlay' explanations (now using Buffers abstraction)
- Simplified struct field documentation to be accurate and concise
- Removed unnecessary mentions of 'Ruff's pattern' everywhere
The documentation now accurately reflects the current implementation
without verbose explanations of outdated architecture.
The documentation was completely out of sync with the code:
- Referenced 'overlays in Session using Arc<DashMap>' when they're now in Buffers
- Mentioned 'LspFileSystem' which was renamed to WorkspaceFileSystem
- Was overly verbose without being helpful - 'vomit of words'
Rewrote to be concise and accurate:
- Correctly describes the current two-layer architecture
- Focuses on the critical revision dependency trick
- Removes outdated implementation details
- Uses proper cross-references
Fixed unclosed HTML tag warnings by adding backticks around:
- Generic types like Arc<DashMap>
- Type names in documentation like StorageHandle<Database>
- The word 'Arc' when referring to the type
- Added comprehensive module-level documentation to all djls-workspace modules
- Consolidated scattered URL/path conversion utilities into paths module
- Added documentation explaining the 'why' for key types and abstractions
- Added #[must_use] annotations to constructors and getters
- Focused on explaining architecture and design decisions rather than obvious behavior
The core issue was that when a file was opened in the LSP, if it had already
been read from disk, Salsa would return cached content instead of reading
from the overlay system. This happened because opening a file didn't bump
its revision, so Salsa had no reason to invalidate its cache.
Key changes:
- Created Buffers abstraction to encapsulate shared buffer storage
- Fixed Session::open_document() to bump revision when file already exists
- Added comprehensive integration tests to verify overlay behavior
- Refactored WorkspaceFileSystem to use Buffers instead of raw DashMap
This ensures that overlays always take precedence over disk content, fixing
the issue where LSP edits weren't being reflected in template parsing.
