Documentation push on node-add-api

[mhdawson]

[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