docs: Extra information about module tree
This commit is contained in:
parent
edcb6af16f
commit
febb34d119
GPG key ID:
E930CDEC50C50E23
3 changed files with 58 additions and 34 deletions
|
|
@ -2,8 +2,18 @@ For now this project is still pretty small, but here are some general guidelines
|
|||
|
||||
- This project ships with a code style config in .idea, your IDE should automatically apply it when you pull the repo.
|
||||
When making pull requests, please try to keep to this style as much as possible.
|
||||
|
||||
- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), and scope as much as you can.
|
||||
- The project has support for the PSI tree, but try to keep "intelligent" behaviour out of it, all code inspection and
|
||||
other semantics-aware help should come from ZLS where possible.
|
||||
- Generally, if the answer to "Can i write some glue code that can get this info from ZLS?" is YES, do not use the PSI
|
||||
tree.
|
||||
|
||||
- Do not edit the relationship tree between modules without unanimous agreement from the project lead.
|
||||
|
||||
If you want an "upstream" module (for instance, the LSP) receive data from a "downstream" module
|
||||
(for instance, the project module), you should use service providers, dependency injections, or other ways to implement
|
||||
the dataflow in a way where the upstream module is not directly aware of downstream modules.
|
||||
|
||||
The main purpose of this is to avoid any circular dependencies, which could cause proprietary IDE-only features
|
||||
(for instance, the CLion debugger module) to be depended on by FOSS modules. This restriction is non-negotiable.
|
||||
|
||||
- Any complex language inspection, syntax action, or similar, should be done by ZLS, and ZigBrains will just act as an
|
||||
adapter for these features. This notion of "complexity" is determined by the project maintainer. Open an issue
|
||||
that explains the feature before you start implementing anything!
|
||||
44
MODULE_TREE.md
Normal file
44
MODULE_TREE.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
## What is this?
|
||||
This document describes the relationships between the different "modules" of ZigBrains.
|
||||
|
||||
These relationships are strictly enforced, and modules that do not directly (or indirectly) depend on another
|
||||
module cannot access their classes.
|
||||
|
||||
The primary purpose of this strictly enforced module system is to avoid code compatible with open source IDEs (IDEA/PyCharm Community)
|
||||
from depending on code that only works on proprietary IDEs (IDEA Ultimate/CLion/...).
|
||||
|
||||
NOTE: These "modules" are in no way related to the module system introduced in Java 9. They're just called the same.
|
||||
|
||||
The suffix after the module name signifies which IDE it depends on.
|
||||
|
||||
- IC: IDEA Community
|
||||
- CL: CLion
|
||||
- EXT: External maven library
|
||||
|
||||
IC modules MUST NOT depend on CL modules, as this violates the restrictions set forth above.
|
||||
|
||||
## Modules
|
||||
|
||||
### Common (IC)
|
||||
|
||||
### LSP (IC)
|
||||
- LSP4J (EXT)
|
||||
- Flexmark (EXT)
|
||||
- Apache Commons Lang 3 (EXT)
|
||||
|
||||
### Zig (IC)
|
||||
- Grammarkit (EXT)
|
||||
- Common (IC)
|
||||
- LSP (IC)
|
||||
|
||||
### Project (IC)
|
||||
- Common (IC)
|
||||
- Zig (IC)
|
||||
|
||||
### Zon (IC)
|
||||
- Grammarkit (EXT)
|
||||
- Common (IC)
|
||||
|
||||
### Debugger (CL)
|
||||
- Zig (IC)
|
||||
- Project (IC)
|
||||
30
README.md
30
README.md
|
|
@ -127,36 +127,6 @@ this yet, but fortunately it doesn't break anything, just a bit of inconvenience
|
|||
- Debugging (CLion/IDEA Ultimate)
|
||||
- Project generation (thanks @JensvandeWiel !)
|
||||
|
||||
## The motivation
|
||||
The other existing Zig language plugins for IntelliJ rely a lot on the PSI tree.
|
||||
This seems correct in theory, until
|
||||
the sheer power of Zig's comptime is taken into consideration.
|
||||
|
||||
The comptime makes any sort of contextual help implemented with the PSI tree a lot more restrictive,
|
||||
and adding LSP integration at that point is an uphill battle.
|
||||
|
||||
## Current state of the project
|
||||
This project takes the opposite approach: The initial implementation *completely* relies on ZLS, with no lexer or parser
|
||||
in sight.
|
||||
Using a language server immediately gives us access to advanced features such as refactoring, go to definition,
|
||||
semantics-based highlighting, and so on.
|
||||
|
||||
However, this also restricts the amount of IDE integration the language plugin can achieve,
|
||||
and things like live previews, peek definition, go to usage previews, and many other features that deeply integrate with
|
||||
the PSI system just don't work at all.
|
||||
|
||||
## Long-term plans
|
||||
The first and foremost goal of this project is deeply integrating ZLS into the IDE,
|
||||
and LSP-provided information *always* takes the first seat.
|
||||
|
||||
However, we must also not completely reject the PSI tree,
|
||||
as it has its own merits when used wisely, such as basic "dumb mode" syntax highlighting,
|
||||
proper caret placements with go to usages, and so on.
|
||||
|
||||
Thus, this project will still use PSI trees and the IntelliJ lexer/parser system, but with heavy moderation, and any
|
||||
sort of "smart inspection" *shall not* be implemented in the PSI, but instead retrieved from the language server.
|
||||
|
||||
|
||||
## Licenses
|
||||
|
||||
<p>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue