CONTRIBUTING.md

   1 The project is in its early stages: contributions are welcome and would be
   2 **very** helpful, but the project is not _yet_ optimized for contribution.
   3 Moreover, it is doubly experimental, so there's no guarantee that any work here
   4 would reach production. That said, here are some areas where contributions would
   5 be **especially** welcome:
   6
   7 - Designing internal data structures: RFC only outlines the constraints, it's an
   8   open question how to satisfy them in the optimal way. See `ARCHITECTURE.md`
   9   for current design questions.
  10
  11 - Porting libsyntax parser to rust-analyzer: currently rust-analyzer parses only
  12   a tiny subset of Rust. This should be fixed by porting parsing functions from
  13   libsyntax one by one. Take a look at the [libsyntax parser] for "what to port"
  14   and at the [Kotlin parser] for "how to port".
  15
  16 - Writing validators: by design, rust-analyzer is very lax about the input. For
  17   example, the lexer happily accepts unclosed strings. The idea is that there
  18   should be a higher level visitor, which walks the syntax tree after parsing
  19   and produces all the warnings. Alas, there's no such visitor yet :( Would you
  20   like to write one? :)
  21
  22 - Creating tests: it would be tremendously helpful to read each of libsyntax and
  23   rust-analyzer parser functions and crate a small separate test cases to cover
  24   each and every edge case.
  25
  26 - Building stuff with rust-analyzer: it would be really cool to compile
  27   rust-analyzer to WASM and add _client side_ syntax validation to rust
  28   playground!
  29
  30 Do take a look at the issue tracker.
  31
  32 If you don't know where to start, or have _any_ questions or suggestions, don't
  33 hesitate to chat at [Gitter]!
  34
  35 # Code generation
  36
  37 Some of the components of this repository are generated through automatic
  38 processes. These are outlined below:
  39
  40 - `gen-kinds`: The kinds of tokens are reused in several places, so a generator
  41   is used. This process uses [tera] to generate, using data in [grammar.ron],
  42   the files:
  43   - [ast/generated.rs][ast generated] in `ra_syntax` based on
  44     [ast/generated.tera.rs][ast source]
  45   - [syntax_kinds/generated.rs][syntax_kinds generated] in `ra_syntax` based on
  46     [syntax_kinds/generated.tera.rs][syntax_kinds source]
  47
  48 [libsyntax parser]:
  49   https://github.com/rust-lang/rust/blob/6b99adeb11313197f409b4f7c4083c2ceca8a4fe/src/libsyntax/parse/parser.rs
  50 [kotlin parser]:
  51   https://github.com/JetBrains/kotlin/blob/4d951de616b20feca92f3e9cc9679b2de9e65195/compiler/frontend/src/org/jetbrains/kotlin/parsing/KotlinParsing.java
  52 [gitter]: https://gitter.im/libsyntax2/Lobby
  53 [tera]: https://tera.netlify.com/
  54 [grammar.ron]: ./crates/ra_syntax/src/grammar.ron
  55 [ast generated]: ./crates/ra_syntax/src/ast/generated.rs
  56 [ast source]: ./crates/ra_syntax/src/ast/generated.tera.rs
  57 [syntax_kinds generated]: ./crates/ra_syntax/src/syntax_kinds/generated.rs
  58 [syntax_kinds source]: ./crates/ra_syntax/src/syntax_kinds/generated.tera.rs