Documentation push on node-add-api

[mhdawson]

No description provided.

[mhdawson]

@jschlight, @NickNaso, @corymickelson, @jschlight

[mhdawson]

Cory is going to take a first cut at the outline of the doc, then we'll figure out how to split up the work of moving it forward.

[NickNaso]

Here I report some points that in my opinion we have to insert and disccuss about documentation

• What is Node Addon API (litle overview)

• Reasons and motivations behind the Node Addon API

• Quick start (Very small instructions that allow to start in a fast way)

• Links - reference to more specific parts of the documentation that will be in separate files and treat the following arguments:

  • Installation and usage

  • What is and how to use Environments

  • Scope and EscapableScope

  • What is and how to use Value

  • Creates a JS value from a C++ primitive

  • Creates C++ value from JS value

  • Buffer and TypedArray (They are particular JavaScript object and maybe we need to deepen their usage)

  • Javascript Properties

  • JavaScript Functions

  • Error handling (How to handle the error)

  • ObjectWrap (What is and how to use)

    • Little migration guide to pass from Nan::ObjectWrap

  • AsyncWorker (How to create async function)

    • Little migration guide to pass from Nan::AsyncWorker

  • How to create a module

    • Register a module
    • binding.gyp configuration (Link to some useful resources because sometimes it's very hard to find the right settings)
    • Generator for scaffolding a project of native addon
    • Useful reources tools that help to be more productive
    • Link to the examples (Consider the creation of some complex examples)

  • Conversion tool (How to use and which types of tasks it does for us)

  • News and Updates

At moment there isn't a changelog file it's important to me know the changes happened and maybe the rationale behind them.

After we will write the documentation we could consider the usage of a tool like docsify that will help us to generate site starting from markdown files.

[corymickelson]

Nicola, sorry I've been chatting directly with Michael but we've come up with a similar outline. Setup - node-gyp - cmake-js - ide setup ?? - building for older version <8.6 ?? - Conversion tool Class outline: - Basic Types - Array - Symbol - String - Name - Number - Boolean - Env - Value - CallbackInfo - Reference - External - Object - ObjectReference - PropertyDescriptor - Error Handling - Error - Object Lifetime Management - HandleScope - EscapableHandleScope - Working with Javascript Values - Function - FunctionReference - ObjectWrap - ClassPropertyDescriptor - Buffer - ArrayBuffer - TypedArray - TypedArrayOf - Async Operations - AsyncWorker - Promises Do you think this is good enough to start splitting up the work? In the mean time I've submitted a pull request to update the current doxygen generated docs to 1.0.0

…

On Oct 16, 2017 10:10 PM, "Nicola Del Gobbo" ***@***.***> wrote: Here I report some points that in my opinion we have to insert and disccuss about documentation - What is Node Addon API (litle overview) - Reasons and motivations behind the Node Addon API - Quick start (Very small instructions that allow to start in a fast way) - Links - reference to more specific parts of the documentation that will be in separate files and treat the following arguments: - Installation and usage - What is and how to use Environments - What is and how to use Value - Creates a JS value from a C++ primitive - Creates C++ value from JS value - Buffer and TypedArray (They are particular JavaScript object and maybe we need to deepen their usage) - Javascript Properties - JavaScript Functions - Error handling (How to handle the error) - ObjectWrap (What is and how to use) - Little migration guide to pass from Nan::ObjectWrap - AsyncWorker (How to create async function) - Little migration guid to pass from Nan::AsyncWorker - Conversion tool (How to use and which types of tasks it does for us) - News and Updates At moment there isn't a changelog file it's important to me know the changes happened and maybe the rationale behind them. After we will write the documentation we could consider the usage of a tool like docsify <https://docsify.js.org> that will help us to generate site starting from markdown files. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#280 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH8LDnxULxdn_KQ6EmRqs9N62X-dtaEdks5stDasgaJpZM4P3XuB> .

[NickNaso]

@corymickelson don't worry for me it's good to know that we are aligned on what we have to do.
I think that based on this proposal we can discuss on how to split our work.
The first step could be define some guidelines that we have to follow on writing documentation so at the end even if we split the tasks all will be similar and coherent.

[corymickelson]

I personally prefer the MDN docs outline: Class Name - Intro / Description - Syntax - parameters, return value(s), and exception(s) - Examples - Links Does anyone have any issue with using markdown? Docsify looks good, there's also mkdocs <http://www.mkdocs.org/>, both look to be very similar.

…

On Tue, Oct 17, 2017 at 9:58 AM, Nicola Del Gobbo ***@***.***> wrote: @corymickelson <https://github.com/corymickelson> don't worry for me it's good to know that we are aligned on what we have to do. I think that based on this proposal we can discuss on how to split our work. The first step could be define some guidelines that we have to follow on writing documentation so at the end even if we split the tasks all will be similar and coherent. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#280 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH8LDuKEMJXKPA4QERSMwCvUtEYIBCWDks5stNzRgaJpZM4P3XuB> .

[jschlight]

Markdown works for me. I do not have a preference between Docsify and MkDocs.

[NickNaso]

Yes for me markdown is the right solution and then after this first step we can use one of the available tools out there to make the documentation more usable.
If you want in this week I can start to write something for the Setup part

[digitalinfinity]

+1 for Markdown. One thing that @jasongin and I talked about a while back was whether we should have some documentation in the header file itself that we could extract out at package creation or build time to produce the API documentation automatically- it has some nice benefits in that if someone is using an IDE for developing their addon, the documentation for the API they're using can be made available within their IDE. My personal view is that it would be awesome if we could have API docs in the headers and have something that extracts them out and combines them with the other markdown documentation but I'll defer to y'all 😄

[corymickelson]

Here <https://docs.google.com/spreadsheets/d/1YbEQNTIv88MQoINdtPQyYIjCBS7kfCnZUrFJWSTYjPs/edit?usp=sharing> is a spread sheet, maybe we can put our names next to the documents we are going to work on

…

On Tue, Oct 17, 2017 at 11:39 AM, Nicola Del Gobbo ***@***.*** > wrote: Yes for me markdown is the right solution and then after this first step we can use one of the available tools out there to make the documentation more usable. If you want in this week I can start to write something for the *Setup* part — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#280 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH8LDtkTORgo5-D3Cz_X1bIzUjiRggkVks5stPRegaJpZM4P3XuB> .

[mhdawson]

Markdown makes sense to me a well as that is what the standard Node.js API doc is in.

[mhdawson]

Probably good to review this Issue to make sure we cover the issues mentioned there:

nodejs/node-addon-api#91

[jschlight]

I am close to being ready to upload the first draft of the documentation I've been working on for review and criticism. What's the best way to go about that?

[corymickelson]

Can you upload to a new repo, or a fork of node-addon-api?

…

On Wed, Oct 25, 2017 at 1:25 PM, Jim Schlight ***@***.***> wrote: I am close to being ready to upload the first draft of the documentation I've been working on for review and criticism. What's the best way to go about that? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#280 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH8LDlz_Hy_Y4bzGSQ5fzJEyFlMF6X4iks5sv5lDgaJpZM4P3XuB> .

[mhdawson]

Also of note nodejs/node-addon-api#162

[mhdawson]

A fork of the node-addon-api would be best in my opinion. You can then submit a PR against the main repo which is often the easiest way for people to review/comment as they can add comments on specific lines.

[jschlight]

I've just added a pull request nodejs/node-addon-api#165

[NickNaso]

Hi guys I started yesterday to work on documentation beginning from the readme file this evening I will pass to setup part all is present here https://github.com/NickNaso/node-addon-api but at moment is all a working progress work if you want I can make a PR

[corymickelson]

@jschlight Can you meet @NickNaso and myself tomorrow around noon (pacific time) on google hangout to go over documentation work.

[jschlight]

Yes. I'm available and have got it on my calendar.

[mhdawson]

@NickNaso took a quick look at https://github.com/NickNaso/node-addon-api and looks like you have a good start on a number of areas. A PR would make it easier to comment/discuss and also lets us land it in the repo after discussion (even if its not fully complete yet).

[NickNaso]

Just ended documentation for setup, added sections tests - examples on readme
See: nodejs/node-addon-api#182

[NickNaso]

Hi everyone,
about documentation I did some research and tested some tools that we could use after we will finish to write the markdown.
I report two of them:

• Docusaurus - created and used by Facebook - It allow to addcustom page, handle the versioning and the research inside the doc.
• Metalsmith - usually is used to build static website and support the markdown. (It's used to build documentation of fastify framework)
  Personally I prefer Docusaurus. What do you think about that? Someone of you have some others ideas or tools to propose?

[mhdawson]

These tools are used to manage md files? At some point we may want to integrate the docs here into the Node.js docs and think we want to avoid using a tool that might prevent that. Lets discuss in one of our upcoming meetings.

[NickNaso]

Documentation status

Below you can see what part of the docs are completed.

• Setup
  • Installation and usage
  • node-gyp
  • cmake-js
  • Conversion tool
  • Generator
• API Documentation
  • Basic Types
  • Array
  • Symbol
  • String
  • Name
  • Number
  • Boolean
  • Env
  • Value
  • CallbackInfo
  • Reference
  • External
  • Object
    • ObjectReference
    • PropertyDescriptor
• Error Handling
  • Error
• Object Lifettime Management
  • HandleScope
  • EscapableHandleScope
• Working with JavaScript Values
  • Function
  • FunctionReference
  • ObjectWrap
    • ClassPropertyDescriptor
  • Buffer
  • ArrayBuffer
  • TypedArray
  • TypedArrayOf
• Async Operations
  • AsyncWorker
• Promises

[mhdawson]

@NickNaso thanks for putting that together.

[mhdawson]

Hitesh
Basic Types
Array
Symbol
String
Name

Michael
Object Lifettime Management
HandleScope
EscapableHandleScope

Kyle
Buffer
ArrayBuffer
TypedArray
TypedArrayOf

Anisha
Reference
External
Object
ObjectReference
PropertyDescriptor

Nick
Error
AsyncWorker
Function
FunctionReference
ObjectWrap
ClassPropertyDescriptor

[kfarnung]

Opened nodejs/node-addon-api#256 for ArrayBuffer and Buffer.

[NickNaso]

Opened nodejs/node-addon-api#259 for error handling

[NickNaso]

Opened nodejs/node-addon-api#272 for asynchronous operation It's a first step I need review and suggestion to improve the doc.

[mhdawson]

We need to look at DataView as well.

[mhdawson]

Nick
Function
FunctionReference
ObjectWrap
ClassPropertyDescriptor

Anisha
ObjectReference
PropertyDescriptor

Kyle
Buffer
ArrayBuffer
TypedArray
TypedArrayOf

[mhdawson]

@kfarnung are you going to get to those tagged with your name above? We would like to get done by Node Summit. If necessary we can split them up to get some people to do one or more of them.

[mhdawson]

In addition to completing the remaining sections above we should

• Update documentation so that we include the Napi namespace consitently. Ie Napi::Value instead of Value
• review to see if everything is covered
• remove the remaining comments about things being under development.

[kfarnung]

I'll plan to get the remaining two done next week.

[mhdawson]

Thanks to everybody for all of the hard work. Now that nodejs/node-addon-api#335 landed I think we can close this. We will continually refine/improve the documentation but now it is complete and in reasonable shape to make sure we maintain coverage.