Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Add initial documentation for N-API #12549

Closed
wants to merge 22 commits into from

Conversation

mhdawson
Copy link
Member

@mhdawson mhdawson commented Apr 20, 2017

Add the initial documentation for the N-API

Rendered

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
Author: Jason Ginchereau <jasongin@microsoft.com>
Author: Michael Dawson <michael_dawson@ca.ibm.com>
Author: Sampson Gao <sampsong@ca.ibm.com>
Author: Taylor Woll <taylor.woll@microsoft.com>
Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc, n-api

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 20, 2017
doc/api/_toc.md Outdated
@@ -24,6 +24,7 @@
* [HTTP](http.html)
* [HTTPS](https.html)
* [Modules](modules.html)
* [N-API](n-api.html)
Copy link
Member

@jasongin jasongin Apr 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be titled something like "C/C++ Addons (N-API)", so that it is adjacent to the other "C/C++ Addons" topic?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

makes sense to me, will update once we have more comments.

@mscdex mscdex added the node-api Issues and PRs related to the Node-API. label Apr 20, 2017
or [Native Abstractions for Node.js][] APIs, the functions available
in the N-API are used instead.

The functions available and how to use them are document in the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

documented?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

Copy link
Contributor

@cjihrig cjihrig left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't make it through the entire PR, but it looks pretty good. Can you make an effort to remove language like "your". 👍


## N-API

N-API is a newer API for building native Addons. It is independent from
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would drop newer here. Otherwise, it will probably claim to be new for years to come.


## N-API

N-API is a newer API for building native Addons. It is independent from
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know if we standardized anywhere, but you have two spaces after some sentences, and one period after others.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should standardise, probably on 1.

changes in the underlying JavaScript engine and allow modules
compiled for one version to run on later versions of Node.js without
recompilation. Addons are built/packaged with the same approach/tools
outlined in this document(node-gyp, etc.). The only difference is the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a space after "document"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

outlined in this document(node-gyp, etc.). The only difference is the
set of APIs that are used by the native code. Instead of using the V8
or [Native Abstractions for Node.js][] APIs, the functions available
in the N-API are used instead.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence begins and ends with "instead." I think the second one can be dropped.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

doc/api/n-api.md Outdated
outlined the second titled [C/C++ Addons](addons.html).
The only difference is the set of APIs that are used by the native code.
Instead of using the V8 or [Native Abstractions for Node.js][] APIs,
the functions available in the N-API are used instead.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comments in these first two paragraphs apply.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

doc/api/n-api.md Outdated
```

`napi_get_last_error_info()` returns the information for the last
N-API call that was made and the `error_code` will match the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe start a new sentence at "and the"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

doc/api/n-api.md Outdated
napi_is_exception_pending()
```

and then check the value of `result`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could probably be combined with the last sentence of the previous paragraph.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

doc/api/n-api.md Outdated
and then return to JavaScript where the exception can be handled.

The second approach is to try to handle the exception. There will be cases
where the native code can 'catch' the exception, take the appropriate action,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does catch need to be in single quotes?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does flow better without, removed.

doc/api/n-api.md Outdated
napi_get_and_clear_last_exception()
```

On success, result will contain the handle to the JavaScript `Error` object.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this guaranteed to be an Error object, or can it be whatever was thrown by JS?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a good point, it will be whatever was thrown.

doc/api/n-api.md Outdated
```

The following utility functions are also available in case your native
code needs to create an error object:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

error -> Error

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

doc/api/n-api.md Outdated
recompilation.

Addons are built/packaged with the same approach/tools
outlined the second titled [C/C++ Addons](addons.html).
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt Apr 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the second -> in the section?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

doc/api/n-api.md Outdated
napi_value value,
int initial_refcount,
napi_ref* result);
##### Parameters
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing backticks above

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

doc/api/n-api.md Outdated
```C
napi_open_escapable_handle_scope()
napi_close_escapable_handle_scope()

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing backticks above

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

doc/api/n-api.md Outdated
##### Description
This represents the underlying binary scalar datatype of the TypedArray.
Elements of this enum correspond to
[Section 22.2] (https://tc39.github.io/ecma262/#sec-typedarray-objects)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

buggy space

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

doc/api/n-api.md Outdated
##### Parameters
- `[in] env `: The environment that the API is invoked under
- `[in] msg`: `napi_value` to be checked
- `[out] `result`: boolean value. Set to true if `napi_value` represents
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wrong backtick

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

doc/api/n-api.md Outdated

#### Description
This API implements the abstract operation ToString as defined in
[Section 7.1.13](http
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt Apr 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

data' -> data`

It seems this is a bug in GitHub: this comment is for line 2873, but it is misplaced here due to possibly long diff (+ diff is truncated here). Beware other comments for the distant lines may be misplaced too.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

@vsemozhetbyt
Copy link
Contributor

Till #12554 fixed, maybe it is reasonable to split very big docs into several parts for review time.

@mhdawson
Copy link
Member Author

Did a pass

  • replacing spaces after period with one space
  • moving use of your

@mhdawson
Copy link
Member Author

@cjihrig @vsemozhetbyt pushed commits to address all comments so far.

@mhdawson
Copy link
Member Author

I'm happy to split up into separate PRs or review in this single PR. I'll leave it up to the reviewers to comment on which they think in best.

doc/api/n-api.md Outdated
the functions available in the N-API are used.


APIs exposed by N-AP are generally used to create and manipulate
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

N-API

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

doc/api/n-api.md Outdated


N-API is an API for building native Addons. It is independent from
the underlying JavaScript runtime (ex v8) and is maintained as part of
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

V8

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

## N-API

N-API is an API for building native Addons. It is independent from
the underlying JavaScript runtime (ex v8) and is maintained as part of
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

V8

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

@Fishrock123
Copy link
Contributor

Added a rendered link in the OP, points to the branch, not a specific commit: https://github.com/mhdawson/io.js/blob/napi-doc/doc/api/n-api.md

@Fishrock123
Copy link
Contributor

Fishrock123 commented Apr 21, 2017

Can we get rid of the Signature, Parameters, Return value, Description mini-headers? They take up a lot of space in the long document and are unnecessary. We could move it to be more like a JS api example, for consistency and readability.

Consider this comparison:


napi_close_handle_scope

Signature
NODE_EXTERN napi_status napi_close_handle_scope(napi_env e,
                                                napi_handle_scope scope);
Parameters
  • [in] env : The environment that the API is invoked under
  • [in] scope: napi_value representing the scope to be closed
Return value
  • napi_ok if the API succeeded.
Description

This API closes the scope passed in. Scopes must be closed in the
reverse order from which they were created.


vs


napi_close_handle_scope

NODE_EXTERN napi_status napi_close_handle_scope(napi_env e,
                                                napi_handle_scope scope);
  • [in] env : The environment that the API is invoked under
  • [in] scope: napi_value representing the scope to be closed

Returns napi_ok if the API succeeded.

This API closes the scope passed in. Scopes must be closed in the
reverse order from which they were created.


@Fishrock123
Copy link
Contributor

Also, can we add added-in placeholders to the API methods?

doc/api/n-api.md Outdated

##### Description
This API closes the scope passed in. Scopes must be closed in the
reverse order from which they were created.o
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

created.o is a typo

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

doc/api/n-api.md Outdated

The N-API is a C API that ensures ABI stability
across Node.js versions and different compiler levels. However, we also
understand that a C++ API can be easier/faster to use in many
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph seems to be talking about C++ wrappers around N-API, so I would strike faster here – they would be easier but they would inherently be limited to being as fast as N-API at best

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

meant faster in terms of development not speed, but remove to avoid confusion

doc/api/n-api.md Outdated
users to manage the lifetimes of JavaScript values, including defining their
minimum lifetimes explicitly.

For more details, review the [Object Lifetime Management section](TODO://path).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

doc/api/n-api.md Outdated
The `napi_status` return value provides a VM-independent representation of
the error which occurred. In some cases it is useful to be able to get
more detailed information, including a string representing the error as well as
VM (engine)-specific information. **NOTE:** you should not rely on the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Notes should be on separate paragraphs and not be all uppercase, followed by a capitalized sentence, i.e. *Note:* You should …

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, and fixed other instances as well.

doc/api/n-api.md Outdated
In order to retrieve this information, the following method is provided:

```C
NODE_EXTERN const napi_extended_error_info* napi_get_last_error_info();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not the actual signature, though?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, to keep thing shorter and because we have the full signature/details in the later sections moved it from these earlier references.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe adding ... for the parameters would help ?

doc/api/n-api.md Outdated
```

`napi_get_last_error_info()` returns the information for the last
N-API call that was made. Tthe `error_code` will match the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: Tthe and double space after it

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

doc/api/n-api.md Outdated
ArrayBuffer. It's also safe to use the returned data buffer within the same
callback as long as you don't call any other APIs that might trigger a GC.

<TODO: What happens to this buffer in case of a compacting GC?>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you’re talking about the data pointer possibly being moved: That does not happen. :)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed TODO.

doc/api/n-api.md Outdated
- `napi_boolean_expected` if a non-boolean `napi_value` is passed in

##### Description
This API retuns C++ boolean primitive equivalent of the given JavaScript
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: returns, also s/C++/C/ again

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed, and also went through and looked for other cases as well.

doc/api/n-api.md Outdated
- `napi_number_expected` if a non-number `napi_value` is passed in

##### Description
This API returns the C++ double primitive equivalent of the given JavaScript
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/C++/C/ (going to stop commenting that now 😄)

doc/api/n-api.md Outdated
- `napi_invalid_arg` if a non-external `napi_value` is passed in

##### Description
This API returns the Pointer to the data wrapped by the JavaScript
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: lowercase pointer

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

doc/api/n-api.md Outdated

##### Description
This API returns the C++ int32 primitive equivalent
of the given JavaScript Number
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These should probably mention what happens when the value does not fit into the corresponding range?

Copy link
Member

@jasnell jasnell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couple of issues

@@ -213,6 +213,24 @@ Addon developers are recommended to use to keep compatibility between past and
future releases of V8 and Node.js. See the `nan` [examples][] for an
illustration of how it can be used.


## N-API

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should include the Experimental stability index flag here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, we have that in the actual section on n-api but I can add here as well

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having it in both places is good.

doc/api/n-api.md Outdated
`napi_pending_exception` will be returned.

In cases where a return value other than `napi_ok` or
`napi_pending_exception` is returned, you must call
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please avoid the use of you in the docs... here and throughout.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did a pass removing all of the 'you's.

doc/api/n-api.md Outdated
#### napi_throw
##### Signature
```C
NODE_EXTERN napi_status napi_throw(napi_env e, napi_value error);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here and throughout, can we make sure that the signature has the same names as the listed parameters?

e.g. e should be env to match.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed all of the env instances.

@mhdawson
Copy link
Member Author

@addaleax @jasnell @Fishrock123 pushed commits to address all of the comments so far. Note that the short links render ok when you do make doc and view as html as opposed to what you see when you look at the rendered markdown link you posted.

@vsemozhetbyt
Copy link
Contributor

vsemozhetbyt commented Apr 25, 2017

This does not pass new doc linting:

  1987:1   error  Unexpected var, use let or const instead                                       no-var
  2011:1   error  Unexpected var, use let or const instead                                       no-var
  2035:1   error  Unexpected var, use let or const instead                                       no-var
  2036:1   error  Unexpected var, use let or const instead                                       no-var
  2056:1   error  Unexpected var, use let or const instead                                       no-var
  2455:1   error  Opening curly brace does not appear on the same line as controlling statement  brace-style
  2456:5   error  Expected indentation of 2 spaces but found 4                                   indent
  2546:1   error  Unexpected var, use let or const instead                                       no-var
  2630:1   error  Opening curly brace does not appear on the same line as controlling statement  brace-style
  2631:5   error  Expected indentation of 2 spaces but found 4                                   indent
  2634:1   error  Unexpected var, use let or const instead                                       no-var
  2634:11  error  Strings must use singlequote                                                   quotes
  2635:1   error  Unexpected var, use let or const instead                                       no-var

✖ 13 problems (13 errors, 0 warnings)

Lines like this also may need to be addressed for consistency:

// var obj = {}

Testing Linter CI: https://ci.nodejs.org/job/node-test-linter/8536/

Strange. Why Linting passes on CI?

Testing if full CI also passes with linting: https://ci.nodejs.org/job/node-test-pull-request/7659/ (passes, 1 Windows fail seems unrelated).

See #12635 and #12640

Copy link
Contributor

@Fishrock123 Fishrock123 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good! Couple more comments.

Also, according to the github diff renderer formatting breaks halfway through... It is possible that is just because the diff it too large but we should check for markdown errors in case.

doc/api/n-api.md Outdated
Integral status code indicating the success or failure of a N-API call.
Currently, the following status codes are supported.
```C
napi_ok,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be an enum def?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change to be enum definition

doc/api/n-api.md Outdated
it can be obtained by calling `napi_get_last_error_info`.

### *napi_extended_error_info*
#### Definition
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we apply the same hear rules to e.g. here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what you mean here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you meant removing the headers (Definition and Members) I went ahead and did that. Seems better to me.

doc/api/n-api.md Outdated
not implemented for any VM.
- engine_error_code: VM-specific error code. This is currently
not implemented for any VM.
- error_code: the N-API status code that originated with the last error
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

- `member`: Regular grammar rules.

Ditto for the parameters section of most APIs. I think this is the style we use elsewhere.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what you mean here either.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the point is:

error_code -> `error_code`

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok guessing that it meant the parameter sections use use regular grammar including capital at the start and period at the end. Went through and fixed all that up.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, fixed error_code -> error_code as well. It was pretty much ok except for the instance identified.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that's what I meant. Code blocks and grammar. Sorry.

doc/api/n-api.md Outdated
const napi_extended_error_info** result);
```
- `[in] env`: The environment that the API is invoked under
- `[out] result`: The `napi_extended_error_info` structure with more
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use 1 space between [in/out] and name? Here and throughout. They don't render with more than 1 space it seems anyways?

(Unless make doc does, but I doubt it?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

Add the initial documentation for the N-API

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

    Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
    Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
    Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
    Author: Jason Ginchereau <jasongin@microsoft.com>
    Author: Michael Dawson <michael_dawson@ca.ibm.com>
    Author: Sampson Gao <sampsong@ca.ibm.com>
    Author: Taylor Woll <taylor.woll@microsoft.com>
@mhdawson
Copy link
Member Author

@Fishrock123 github/large file may not be helping us here as I'm not 100% sure what's left with respect to https://github.com/nodejs/node/pull/12549/files#r112795649. I already added the stability index as James requested and I think that's the comment that that one shows me.

@mhdawson
Copy link
Member Author

@Fishrock123 I don't have any great ideas on the headings right now, so I'd prefer to land this and then I can spend a bit more time and maybe come up with something in a later PR.

Copy link
Contributor

@Fishrock123 Fishrock123 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mhdawson Oh whoops, didn't see it on the line below. LGTM to me on doc style. (I didn't review the APIs in detail.)

@mhdawson
Copy link
Member Author

@addaleax I think I've addressed your issues so I plan to land soon. If not just let me know.

CI run: https://ci.nodejs.org/job/node-test-pull-request/7734/

@mhdawson mhdawson closed this Apr 28, 2017
@mhdawson mhdawson reopened this Apr 28, 2017
@addaleax
Copy link
Member

@mhdawson Yeah, sorry, didn’t have the time to give it a full review. So please don’t let me hold up anything! :)

@mhdawson
Copy link
Member Author

@addaleax thanks. Of course if you spot anything later on just let me know and I'll cover it in a later PR.

@mhdawson
Copy link
Member Author

Ok CI good, landing.

mhdawson added a commit that referenced this pull request Apr 28, 2017
Add the initial documentation for the N-API

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
Author: Jason Ginchereau <jasongin@microsoft.com>
Author: Michael Dawson <michael_dawson@ca.ibm.com>
Author: Sampson Gao <sampsong@ca.ibm.com>
Author: Taylor Woll <taylor.woll@microsoft.com>

PR-URL: #12549
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
@mhdawson
Copy link
Member Author

landed as deb9622

@mhdawson mhdawson closed this Apr 28, 2017
@evanlucas evanlucas mentioned this pull request May 1, 2017
evanlucas pushed a commit that referenced this pull request May 1, 2017
Add the initial documentation for the N-API

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
Author: Jason Ginchereau <jasongin@microsoft.com>
Author: Michael Dawson <michael_dawson@ca.ibm.com>
Author: Sampson Gao <sampsong@ca.ibm.com>
Author: Taylor Woll <taylor.woll@microsoft.com>

PR-URL: #12549
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
evanlucas pushed a commit that referenced this pull request May 2, 2017
Add the initial documentation for the N-API

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
Author: Jason Ginchereau <jasongin@microsoft.com>
Author: Michael Dawson <michael_dawson@ca.ibm.com>
Author: Sampson Gao <sampsong@ca.ibm.com>
Author: Taylor Woll <taylor.woll@microsoft.com>

PR-URL: #12549
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
evanlucas pushed a commit that referenced this pull request May 2, 2017
Add the initial documentation for the N-API

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
Author: Jason Ginchereau <jasongin@microsoft.com>
Author: Michael Dawson <michael_dawson@ca.ibm.com>
Author: Sampson Gao <sampsong@ca.ibm.com>
Author: Taylor Woll <taylor.woll@microsoft.com>

PR-URL: #12549
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
@refack
Copy link
Contributor

refack commented May 8, 2017

NM

@jasnell jasnell mentioned this pull request May 11, 2017
@mhdawson mhdawson deleted the napi-doc branch June 28, 2017 19:24
gabrielschulhof pushed a commit to gabrielschulhof/node that referenced this pull request Apr 10, 2018
Add the initial documentation for the N-API

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
Author: Jason Ginchereau <jasongin@microsoft.com>
Author: Michael Dawson <michael_dawson@ca.ibm.com>
Author: Sampson Gao <sampsong@ca.ibm.com>
Author: Taylor Woll <taylor.woll@microsoft.com>

PR-URL: nodejs#12549
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
MylesBorins pushed a commit that referenced this pull request Apr 16, 2018
Add the initial documentation for the N-API

This PR is a result of work in the abi-stable-node repo:
https://github.com/nodejs/abi-stable-node/tree/doc,
with this PR being the cumulative work on the documentation
sections in that repo with the following contributors
in alphabetical order:

Author: Arunesh Chandra <arunesh.chandra@microsoft.com>
Author: Gabriel Schulhof <gabriel.schulhof@intel.com>
Author: Hitesh Kanwathirtha <hiteshk@microsoft.com>
Author: Jason Ginchereau <jasongin@microsoft.com>
Author: Michael Dawson <michael_dawson@ca.ibm.com>
Author: Sampson Gao <sampsong@ca.ibm.com>
Author: Taylor Woll <taylor.woll@microsoft.com>

Backport-PR-URL: #19447
PR-URL: #12549
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Apr 16, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. node-api Issues and PRs related to the Node-API.
Projects
None yet
Development

Successfully merging this pull request may close these issues.