Improve docs in core (denoland#2049)

core/Cargo.toml

@@ -7,6 +7,8 @@ edition = "2018"
 description = "A secure JavaScript/TypeScript runtime built with V8, Rust, and Tokio"
 authors = ["The deno authors <[email protected]>"]
 license = "MIT"
+readme = "README.md"
+repository = "https://github.com/denoland/deno"
 
 [lib]
 path = "lib.rs"

core/README.md

@@ -0,0 +1,16 @@
+# Deno Core
+
+This Rust crate contains the essential V8 bindings for Deno's command-line
+interface (Deno CLI). The main abstraction here is the Isolate which proivdes a
+way to execute JavaScript. The Isolate is modeled as a
+`Future<Item=(), Error=JSError>` which completes once all of its ops have
+completed. The user must define what an Op is by implementing the `Behavior`
+trait, and by doing so define any "built-in" functionality that would be
+provided by the VM. Ops are triggered by `Deno.core.dispatch()`.
+
+Documentation for this crate is thin at the moment. Please see
+[http_bench.rs](https://github.com/denoland/deno/blob/master/core/http_bench.rs)
+as a simple example of usage.
+
+TypeScript support and a lot of other functionality is not available at this
+layer. See the [cli](https://github.com/denoland/deno/tree/master/cli) for that.

core/isolate.rs

@@ -68,8 +68,8 @@ pub trait Behavior {
  /// Isolate is created.
  fn startup_data(&mut self) -> Option<StartupData>;
 
- /// Called whenever Deno.core.send() is called in JavaScript. zero_copy_buf
- /// corresponds to the second argument of Deno.core.send().
+ /// Called whenever Deno.core.dispatch() is called in JavaScript. zero_copy_buf
+ /// corresponds to the second argument of Deno.core.dispatch().
  fn dispatch(
  &mut self,
  control: &[u8],
@@ -82,9 +82,9 @@ pub trait Behavior {
 /// Tokio. The Isolate future complete when there is an error or when all
 /// pending ops have completed.
 ///
-/// Ops are created in JavaScript by calling Deno.core.send(), and in Rust by
-/// implementing Behavior::dispatch. An Op corresponds exactly to a Promise in
-/// JavaScript.
+/// Ops are created in JavaScript by calling Deno.core.dispatch(), and in Rust
+/// by implementing deno::Behavior::dispatch. An Op corresponds exactly to a
+/// Promise in JavaScript.
 pub struct Isolate<B: Behavior> {
  libdeno_isolate: *const libdeno::isolate,
  shared_libdeno_isolate: Arc<Mutex<Option<*const libdeno::isolate>>>,

website/manual.md

@@ -50,7 +50,7 @@ Deno provides <a href="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/denoland/deno_std">a set of reviewed
 - File system and network access can be controlled in order to run sandboxed
  code. Access between V8 (unprivileged) and Rust (privileged) is only done via
  serialized messages defined in this
- [flatbuffer](https://github.com/denoland/deno/blob/master/src/msg.fbs). This
+ [flatbuffer](https://github.com/denoland/deno/blob/master/cli/msg.fbs). This
  makes it easy to audit. For example, to enable write access use the flag
  `--allow-write` or for network access `--allow-net`.
 
@@ -705,21 +705,18 @@ Current executable set to '../deno/target/debug/deno' (x86_64).
 (lldb) r
 ```
 
-### libdeno
+### Deno Core
 
-deno's privileged side will primarily be programmed in Rust. However there will
-be a small C API that wraps V8 to 1) define the low-level message passing
-semantics, 2) provide a low-level test target, 3) provide an ANSI C API binding
-interface for Rust. V8 plus this C API is called "libdeno" and the important
-bits of the API is specified here:
-[deno.h](https://github.com/denoland/deno/blob/master/libdeno/deno.h)
-[libdeno.ts](https://github.com/denoland/deno/blob/master/js/libdeno.ts)
+The core binding layer for Deno. It is released as a
+[standalone crate](https://crates.io/crates/deno). Inside of core is V8 itself,
+with a binding API called "libdeno". See the crate documentation for more
+details.
 
 ### Flatbuffers
 
 We use Flatbuffers to define common structs and enums between TypeScript and
 Rust. These common data structures are defined in
-[msg.fbs](https://github.com/denoland/deno/blob/master/src/msg.fbs)
+[msg.fbs](https://github.com/denoland/deno/blob/master/cli/msg.fbs)
 
 ### Updating prebuilt binaries