Documentation Improvements: How to do basic things with ChakraCore

[dilijev]

Adapted from internal feedback:

It would have been helpful if there had been a more descriptive documentation explaining about doing basic things using ChakraCore, like how to expose classes to js, how to receive objects from js with the current state, namespaces, how to get/set attributes, how to invoke a js function, and how to export a C++ function to js. We had to dig into the sample projects hosted in the github page to understand how to do things in ChakraCore. A better documentation could have helped and saved time for us.

If this information is already available in a form other than the example projects, we should try to improve the discoverability of that info.

---

Adding @liminzhu's list of topics to the main post so we get the handy progress meter:

• [x] Expose native functions / external objects to JavaScript https://github.com/Microsoft/ChakraCore-wiki/pull/44
• [ ] Embed JavaScript functions in C/C++ (suggested by @kphillisjr in https://github.com/Microsoft/ChakraCore-wiki/issues/5#issuecomment-269926563)
• [x] Handle object lifetime and memory management; common AV issues in .NET
• [x] Implement a simple event-loop and task queue + using promises in JSRT
• [x] Script serialization with lazy source loading https://github.com/Microsoft/ChakraCore-wiki/pull/44
• [x] Resource throttling
• [ ] Define non-writable property from C/C++(a.k.a. using descriptor)
• [ ] Define C/C++ Getter and Setter
• [ ] TypedArray handling in C/C++
• [ ] Iterating JS array ans setting properties in C++
• [x] Call functions https://github.com/Microsoft/ChakraCore-wiki/pull/44
• [ ] Set up ES6 modules + dynamic import
• [ ] Add native interceptors to JavaScript properties

[liminzhu]

NOTE: new edits to the list will be added to the main post instead of to this comment.

Good input. I think I've done all of those in this sample, but some documentation with small code snippets would've been more helpful. I'll look into it when I'm free.

Creating a list of topics,

• [ ] Expose native functions / external objects to JavaScript
• [ ] Handle object lifetime
• [ ] Implement a simple event-loop and task queue + using promises in JSRT
• [ ] Script serialization with lazy source loading
• [ ] Resource throttling
• [ ] Define non-writable property from C/C++(a.k.a. using descriptor)
• [ ] Define C/C++ Getter and Setter
• [ ] TypedArray handling in C/C++

Edited: Add some stuff per https://github.com/Microsoft/Chakra-Samples/issues/51 @kphillisjr

[kphillisjr]

Might want to add "Embed JavaScript functions in C/C++"... This may not be used very often, but there is cases where the implementation of a function is a lot easier to use JavaScript than it is C/C++.

// This is the toString function defined using JavaScript, 
// but is embedded in C/C++ code.
function toString() {
  return `Point (${this.x}, ${this.y}, ${this.z})`
}

[jaredwy]

Something that would provide a lot of value. Something quiet common is how to wrap a c++ object so it is accessible from js.

Something similar to https://chromium.googlesource.com/v8/v8/+/master/samples/process.cc would be good.

[liminzhu]

Yeah. I think this one (I added "external objects" just now) on my list would help,

Expose native functions / external objects to JavaScript

[jaredwy]

Great :)

[dilijev]

Updated list in the main post so we get the progress meter from the issues page as we complete these items.

[jaredwy]

@dilijev It would be good to call out that the samples should be accessible cross platform as well as just windows. The opengl sample is great, but uses some windows only features.

[dilijev]

@jaredwy -- Makes sense. For the APIs that are xplat-compatible, the samples should be xplat-compatible. But because they are example snippets, they might not compile on their own without setting up a project like the samples do. Short samples in documentation will not be perfect and super easy, but may be possible to copy-paste into an existing project.

For the Windows-only APIs, they'll obviously only work on Windows. There are a few of these.

[jaredwy]

@dilijev Yup. It would be good just to avoid things like JSPointerToString and JsGetPropertyNameFromId even in projects that are windows only and c++. That is what threw me the most. I was using the opengl sample as a guide and ended up being thrown when attempting to compile copy and pasted code :)