doc: clarify node.js addons language #12898

BethGriggs · 2017-05-08T15:26:33Z

Fixes: #7129

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

sam-github

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

refack · 2017-05-08T15:36:44Z

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

gibfahn · 2017-05-09T11:44:56Z

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).

mhdawson · 2017-05-09T22:25:43Z

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.

gibfahn · 2017-05-09T22:29:52Z

doc/api/addons.md

@@ -1,6 +1,6 @@
 # C/C++ Addons


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.

refack · 2017-05-10T18:07:06Z

@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

gibfahn · 2017-05-10T20:55:30Z

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.

refack · 2017-05-10T21:31:31Z

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

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

mhdawson · 2017-05-10T22:17:53Z

@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.

refack · 2017-05-10T22:18:54Z

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

gibfahn · 2017-05-11T12:03:51Z

@mhdawson LGTY?

gibfahn · 2017-05-11T12:27:20Z

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

mhdawson

LGTM

sam-github · 2017-05-11T18:09:54Z

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>

MylesBorins · 2017-06-22T17:57:43Z

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: clarify node.js addons language #12898

doc: clarify node.js addons language #12898

BethGriggs commented May 8, 2017

sam-github left a comment

refack commented May 8, 2017 •

edited

Loading

gibfahn commented May 9, 2017

mhdawson commented May 9, 2017

gibfahn May 9, 2017

mhdawson May 10, 2017 •

edited

Loading

refack commented May 10, 2017

gibfahn commented May 10, 2017 •

edited

Loading

refack commented May 10, 2017

mhdawson commented May 10, 2017

refack commented May 10, 2017

gibfahn commented May 11, 2017

gibfahn commented May 11, 2017

mhdawson left a comment

sam-github commented May 11, 2017

MylesBorins commented Jun 22, 2017

doc: clarify node.js addons language #12898

doc: clarify node.js addons language #12898

Conversation

BethGriggs commented May 8, 2017

Checklist

Affected core subsystem(s)

sam-github left a comment

Choose a reason for hiding this comment

refack commented May 8, 2017 • edited Loading

gibfahn commented May 9, 2017

mhdawson commented May 9, 2017

gibfahn May 9, 2017

Choose a reason for hiding this comment

mhdawson May 10, 2017 • edited Loading

Choose a reason for hiding this comment

refack commented May 10, 2017

gibfahn commented May 10, 2017 • edited Loading

refack commented May 10, 2017

mhdawson commented May 10, 2017

refack commented May 10, 2017

gibfahn commented May 11, 2017

gibfahn commented May 11, 2017

mhdawson left a comment

Choose a reason for hiding this comment

sam-github commented May 11, 2017

MylesBorins commented Jun 22, 2017

refack commented May 8, 2017 •

edited

Loading

mhdawson May 10, 2017 •

edited

Loading

gibfahn commented May 10, 2017 •

edited

Loading