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: clarify node.js addons language #12898

Closed
wants to merge 1 commit into from

Conversation

BethGriggs
Copy link
Member

Fixes: #7129

Checklist
Affected core subsystem(s)

doc

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

@sam-github sam-github left a comment

Choose a reason for hiding this comment

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

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

@refack
Copy link
Contributor

refack commented May 8, 2017

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

@gibfahn
Copy link
Member

gibfahn commented May 9, 2017

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
Copy link
Member

mhdawson commented May 9, 2017

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.

@@ -1,6 +1,6 @@
# C/C++ Addons
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member

@mhdawson mhdawson May 10, 2017

Choose a reason for hiding this comment

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

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
Copy link
Contributor

refack commented May 10, 2017

@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
Copy link
Member

gibfahn commented May 10, 2017

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
Copy link
Contributor

refack commented May 10, 2017

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
Copy link
Member

@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
Copy link
Contributor

refack commented May 10, 2017

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.

@gibfahn
Copy link
Member

gibfahn commented May 11, 2017

@mhdawson LGTY?

@gibfahn
Copy link
Member

gibfahn commented May 11, 2017

Copy link
Member

@mhdawson mhdawson left a comment

Choose a reason for hiding this comment

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

LGTM

@sam-github
Copy link
Contributor

Landed in abfd4bf

@sam-github sam-github closed this May 11, 2017
sam-github pushed a commit that referenced this pull request May 11, 2017
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>
anchnk pushed a commit to anchnk/node that referenced this pull request May 19, 2017
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>
@jasnell jasnell mentioned this pull request May 28, 2017
@gibfahn gibfahn mentioned this pull request Jun 15, 2017
3 tasks
@MylesBorins
Copy link
Contributor

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

@BethGriggs BethGriggs deleted the doc-api-addons branch February 21, 2018 15:36
gabrielschulhof pushed a commit to gabrielschulhof/node that referenced this pull request Apr 10, 2018
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 pushed a commit that referenced this pull request Apr 16, 2018
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>
@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
addons Issues and PRs related to native addons. doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Documentation misleads embedders