doc: clarify node.js addons language by BethGriggs · Pull Request #12898 · nodejs/node · GitHub

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

Perhaps in the git commit message "language" should be "are C++"? Other than that, LGTM

@BethGriggs super nice of you 🍰
Maybe add a note about experimental napi for a future PR

Maybe add a note about experimental napi

@refack what specifically would you want adding? An actual sentence would be nice (although it could probably be left for a follow-on PR anyway).

I think the change should likely be made in the title as well (first line in the file), and anything that links to that title.

Good point @mhdawson, worth changing this as well.

I get these matches with a quick (rip)grep, @mhdawson do the n-api ones need changing?

➜  node git:(master) ❯ rg "C/C\+\+ Addons"                                                                                                                                                   ~/wrk/com/node
doc/api/_toc.md
10:* [C/C++ Addons](addons.html)
11:* [C/C++ Addons - N-API](n-api.html)

doc/api/addons.md
1:# C/C++ Addons
234:section titled [C/C++ Addons - N-API](n-api.html).

doc/api/n-api.md
15:outlined in the section titled  [C/C++ Addons](addons.html).

The N-API actually supports writing Addons in C so C/C++ is correct for them. The references to addons.html of course need to be updated everywhere.

@gibfahn @mhdawson what I ment before is that: is this change correct now that we have N-API?

Maybe we should just remove the reference to a language?
Node.js Addons are dynamically-linked shared objects, written in C++, that
->
Node.js Addons are dynamically-linked shared objects that

Also at line 8:

At the moment, the method for implementing Addons is rather complicated,
involving knowledge of several components and APIs

->

At the moment, the method for implementing Addons without a helper library
such as [`nan`](#native-abstractions-for-nodejs) or using the [N-API](#n-api),
is rather complicated, involving knowledge of several components and APIs

what I ment before is that: is this change correct now that we have N-API?

I suspect that this doc should be updated to cover n-api, but that's probably something that can/should be done separately. This change makes sense as-is.

Also if we talk about n-api we need to mention that it's experimental, so I don't think we should just add it in next to nan.

that's probably something that can/should be done separately

probably, but FWIW both nan and N-API are covered lower in the doc.

@refack I had the same discussion with @sam-github and he convinced me this change was ok as existing addons are C++ only and the original section only dealt with them. The nan and later N-API sections were inserted, but the overall flow text not updated well enough to integrate them nicely. What seemed to make sense was to let this change go in now, as it is valid to the section to which it applies, and then plan a more complete update once N-API is no longer experimental.

What seemed to make sense was to let this change go in now, as it is valid to the section to which it applies, and then plan a more complete update once N-API is no longer experimental.

Sound good.

Fixes: nodejs#7129

@mhdawson LGTY?

CI: https://ci.nodejs.org/job/node-test-commit/9812/

LGTM

Landed in abfd4bf

PR-URL: #12898 Fixes: #7129 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

PR-URL: nodejs#12898 Fixes: nodejs#7129 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

This does not land cleanly in LTS. Please feel free to manually backport. Please also feel free to replace do-not-land if it is being backported

PR-URL: nodejs#12898 Fixes: nodejs#7129 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

Backport-PR-URL: #19447 PR-URL: #12898 Fixes: #7129 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

nodejs-github-bot added addons Issues and PRs related to native addons. doc Issues and PRs related to the documentations. labels May 8, 2017

sam-github approved these changes May 8, 2017

View reviewed changes

BethGriggs force-pushed the doc-api-addons branch from f5384c7 to 12e7325 Compare May 8, 2017 15:30

thefourtheye approved these changes May 8, 2017

View reviewed changes

refack approved these changes May 8, 2017

View reviewed changes

addaleax approved these changes May 8, 2017

View reviewed changes

jasnell approved these changes May 8, 2017

View reviewed changes

refack mentioned this pull request May 8, 2017

doc: Add initial documentation for N-API #12549

Closed

3 tasks

Trott approved these changes May 8, 2017

View reviewed changes

gibfahn approved these changes May 8, 2017

View reviewed changes

TimothyGu approved these changes May 9, 2017

View reviewed changes

danbev approved these changes May 9, 2017

View reviewed changes

cjihrig approved these changes May 9, 2017

View reviewed changes

gibfahn reviewed May 9, 2017

View reviewed changes

BethGriggs force-pushed the doc-api-addons branch from 12e7325 to cfa5a75 Compare May 10, 2017 20:44

doc: clarify node.js addons are c++

2b9ab45

Fixes: nodejs#7129

BethGriggs force-pushed the doc-api-addons branch from cfa5a75 to 2b9ab45 Compare May 11, 2017 12:01

gibfahn approved these changes May 11, 2017

View reviewed changes

mhdawson approved these changes May 11, 2017

View reviewed changes

gibfahn mentioned this pull request May 11, 2017

Documentation misleads embedders #7129

Closed

sam-github closed this May 11, 2017

jasnell mentioned this pull request May 28, 2017

8.0.0 Release Proposal #12220

Closed

gibfahn mentioned this pull request Jun 15, 2017

Auditing for 6.11.1 nodejs/Release#230

Closed

3 tasks

MylesBorins added the dont-land-on-v6.x label Jun 22, 2017

BethGriggs deleted the doc-api-addons branch February 21, 2018 15:36

MylesBorins mentioned this pull request Apr 16, 2018

v6.14.2 proposal #19996

Merged

doc: clarify node.js addons language by BethGriggs · Pull Request #12898 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: clarify node.js addons language - #12898

doc: clarify node.js addons language#12898BethGriggs wants to merge 1 commit intonodejs:masternodejs/node:masterfrom BethGriggs:doc-api-addonsBethGriggs/node:doc-api-addonsCopy head branch name to clipboard

Conversation

BethGriggs commented May 8, 2017

Checklist

Affected core subsystem(s)

Uh oh!

sam-github left a comment

Choose a reason for hiding this comment

Uh oh!

refack commented May 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gibfahn commented May 9, 2017

Uh oh!

mhdawson commented May 9, 2017

Uh oh!

gibfahn May 9, 2017

Choose a reason for hiding this comment

Uh oh!

mhdawson May 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

refack commented May 10, 2017

Uh oh!

gibfahn commented May 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

refack commented May 10, 2017

Uh oh!

mhdawson commented May 10, 2017

Uh oh!

refack commented May 10, 2017

Uh oh!

gibfahn commented May 11, 2017

Uh oh!

gibfahn commented May 11, 2017

Uh oh!

mhdawson left a comment

Choose a reason for hiding this comment

Uh oh!

sam-github commented May 11, 2017

Uh oh!

MylesBorins commented Jun 22, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

14 participants

doc: clarify node.js addons language#12898
BethGriggs wants to merge 1 commit into
nodejs:masterfrom
BethGriggs:doc-api-addons

refack commented May 8, 2017 •
edited
Loading

mhdawson May 10, 2017 •
edited
Loading

gibfahn commented May 10, 2017 •
edited
Loading