You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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>
.
@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.
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>
.
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
+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 😄
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>
.
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?
@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.
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.
Activity
mhdawson commentedon Oct 12, 2017
@jschlight, @NickNaso, @corymickelson, @jschlight
mhdawson commentedon Oct 12, 2017
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 commentedon Oct 17, 2017
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)
AsyncWorker (How to create async function)
How to create a module
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 commentedon Oct 17, 2017
NickNaso commentedon Oct 17, 2017
@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 commentedon Oct 17, 2017
jschlight commentedon Oct 17, 2017
Markdown works for me. I do not have a preference between Docsify and MkDocs.
NickNaso commentedon Oct 17, 2017
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 commentedon Oct 17, 2017
+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 commentedon Oct 17, 2017
mhdawson commentedon Oct 18, 2017
Markdown makes sense to me a well as that is what the standard Node.js API doc is in.
mhdawson commentedon Oct 23, 2017
Probably good to review this Issue to make sure we cover the issues mentioned there:
nodejs/node-addon-api#91
jschlight commentedon Oct 25, 2017
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?
12 remaining items
NickNaso commentedon Apr 7, 2018
Documentation status
Below you can see what part of the docs are completed.
mhdawson commentedon Apr 9, 2018
@NickNaso thanks for putting that together.
mhdawson commentedon Apr 12, 2018
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 commentedon May 2, 2018
Opened nodejs/node-addon-api#256 for
ArrayBufferandBuffer.NickNaso commentedon May 3, 2018
Opened nodejs/node-addon-api#259 for
error handlingNickNaso commentedon May 17, 2018
Opened nodejs/node-addon-api#272 for
asynchronous operationIt's a first step I need review and suggestion to improve the doc.mhdawson commentedon Jun 21, 2018
We need to look at DataView as well.
mhdawson commentedon Jul 5, 2018
Nick
FunctionFunctionReferenceObjectWrapClassPropertyDescriptorAnisha
ObjectReferencePropertyDescriptorKyle
BufferArrayBufferTypedArrayTypedArrayOfmhdawson commentedon Jul 5, 2018
@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 commentedon Jul 5, 2018
In addition to completing the remaining sections above we should
Napi::Valueinstead ofValuekfarnung commentedon Jul 5, 2018
I'll plan to get the remaining two done next week.
mhdawson commentedon Sep 21, 2018
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.