Merge pull request #2211 from rtfeldman/editor-documentation

added editor documentation

CONTRIBUTING.md

@@ -22,6 +22,7 @@ Earthly may temporarily use a lot of disk space, up to 90 GB. This disk space is
 - Before making your first pull request, definitely talk to an existing contributor on [Roc Zulip](https://roc.zulipchat.com) first about what you plan to do! This can not only avoid duplicated effort, it can also avoid making a whole PR only to discover it won't be accepted because the change doesn't fit with the goals of the language's design or implementation.
 - It's a good idea to open a work-in-progress pull request as you begin working on something. This way, others can see that you're working on it, which avoids duplicate effort, and others can give feedback sooner rather than later if they notice a problem in the direction things are going. Be sure to include "WIP" in the title of the PR as long as it's not ready for review!
 - Make sure to create a branch on the roc repository for your changes. We do not allow CI to be run on forks for security.
+- You find good first issues [here](https://github.com/rtfeldman/roc/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
 
 ## Can we do better?
 

editor/README.md

@@ -1,7 +1,7 @@
 
 The editor is a work in progress, only a limited subset of Roc expressions are currently supported.
 
-Unlike most editors, we use projectional or structural editing to edit the [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) directly. This will allow for cool features like excellent auto-complete and refactoring.
+Unlike most editors, we use projectional or structural editing to edit the [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) directly. This will allow for cool features like excellent auto-complete, refactoring and never needing to format your code.
 
 ## Getting started
 
@@ -29,3 +29,46 @@ We thank the following open source projects in particular for inspiring us when
 - [rgx](https://github.com/cloudhead/rgx)
 - [elm-editor](https://github.com/jxxcarlson/elm-editor)
 - [iced](https://github.com/hecrj/iced)
+
+## How does it work?
+
+To take a look behind the scenes, open the editor with `./roc edit` or `cargo run edit` and press F11.
+This debug view shows important data structures that can be found in `editor/src/editor/mvc/ed_model.rs`.
+Add or delete some code to see how these data structures are updated.
+
+From roc to render:
+- `./roc edit` or `cargo run edit` is first handled in `cli/src/main.rs`, from there the editor's launch function is called (`editor/src/editor/main.rs`).
+- In `run_event_loop` we initialize the winit window, wgpu, the editor's model(`EdModel`) and start the rendering loop.
+- The `ed_model` is filled in part with data obtained by loading and typechecking the roc file with the same function (`load_and_typecheck`) that is used by the compiler.
+- `ed_model` also contains an `EdModule`, which holds the parsed abstract syntax tree (AST).
+- In the `init_model` function:
+    + The AST is converted into a tree of `MarkupNode`. The different types of `MarkupNode` are similar to the elements/nodes in HTML. A line of roc code is represented as a nested `MarkupNode` containing mostly text `MarkupNode`s. The line `foo = "bar"` is represented as 
+    three text `MarkupNode` representing `foo`, ` = ` and `bar`. Multiple lines of roc code are represented as nested `MarkupNode` that contain other nested `MarkupNode`.
+    + `CodeLines` holds a `Vec` of `String`, each line of code is a `String`. When saving the file, the content of `CodeLines` is written to disk.
+    + `GridNodeMap` maps every position of a char of roc code to a `MarkNodeId`, for easy interaction with the caret.
+- Back in `editor/src/editor/main.rs` we convert the `EdModel` to `RenderedWgpu` by calling `model_to_wgpu`.
+- The `RenderedWgpu` is passed to the `glyph_brush` to draw the characters(glyphs) on the screen.
+
+
+### Important files
+
+To understand how the editor works it is useful to know the most important files:
+- editor/src/editor/main.rs
+- editor/src/editor/mvc/ed_update.rs
+- editor/src/editor/mvc/ed_model.rs
+- editor/src/editor/mvc/ed_view.rs
+- editor/src/editor/render_ast.rs
+- editor/src/editor/render_debug.rs
+
+Important folders/files outside the editor folder:
+- code_markup/src/markup/convert
+- code_markup/src/markup/nodes.rs
+- ast/src/lang/core/def
+- ast/src/lang/core/expr
+- ast/src/lang/core/ast.rs
+- ast/src/lang/env.rs
+
+## Contributing
+
+We welcome new contributors :heart: and are happy to help you get started.
+Check [CONTRIBUTING.md](../CONTRIBUTING.md) for more info.