-
Notifications
You must be signed in to change notification settings - Fork 507
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
Write new documentation #371
Conversation
e777948
to
8327b6d
Compare
f629001
to
168753c
Compare
A checklist of everything I think could be documented after looking through everything. I'll need suggestions from others if I've missed something or you think that we should leave some of these undocumented.
|
Some are mostly internal but cannot be hidden, like certain macros. Some constructors are not exposed or should not be exposed, but it was easier to leave them exposed, e.g. CallbackInfo. And so on. I'll enumerate them next week. On July 24, 2015 6:35:39 AM EEST, Rod Vagg [email protected] wrote:
|
Oh, and anything accepting Handle now should just be for implementatiob reasons on versions before io.js 3.0 and should be documented as only taking Local, because they only take Local for new versions. Similarly, Local Nan::New(Handle) only exists for old versions and should only be internal, but it is still exposed. On July 24, 2015 6:35:39 AM EEST, Rod Vagg [email protected] wrote:
|
I think it only matters after 3.0 doesn't it? We're shipping 4.4 there and 4.5 will have to wait which is where they've ripped it out isn't it? The current nan#next works on my previous work on LevelDOWN with no changes needed for I'm fine with asserting that you need to move away from |
Exactly. Handles are dead. On July 24, 2015 7:39:20 AM EEST, Rod Vagg [email protected] wrote:
|
@kkoopa do we even need the method signature helpers any more? They might be useful to keep for backward-compat but perhaps we should start advising people to use |
https://v8docs.nodesource.com/io.js-3.0/ is available now for V8 doxygen docs |
Both work, but macros are extremely convenient and efficient. They are totally legit. On July 24, 2015 7:01:53 AM CEST, Rod Vagg [email protected] wrote:
|
Cleaned up maybe_types.md and converters.md, added a script @ docs/.build.sh which can be run as |
Cool, having a script for that is very useful (despite it being Perl ;)). The Makefile should also get a |
💥 done! pretty much everything has been documented now, see the unticked items for the ones I decided to not include. README has been trimmed and TOC generated along with a Makefile target and package.json script entry for doing it. The only thing I'm hesitant about here is using relative URLs from the TOC because I don't think npmjs.org rewrites them to point back to GitHub so we may have to do complete URLs; but we can fix that later if need be. PTAL! I'm desperate to get io.js v3 out so we can move on to Node.js v4 and get it all done before the end of August. This is the primary blocker, v3 is ready to roll and I can push do a release proposal as soon as we have nan@2 in npm. Next step for me is to write up a blog post describing what's changed at a high level and giving a conversion process that folks can follow. I'll ping back here when I have that drafted (I'll be working on it from tomorrow!) for feedback. But please don't let that hold up a release. @kkoopa if you have a high enough level of comfort, could you merge next and newdocs and cut a release? I'm happy with the state of things. There's some rough edges in the README and probably the example needs updating but I'd really rather those things not hold up a release as we can fix all of those things up in patch releases after a 2.0.0. |
Sounds like a plan. I'm back from Berlin now. Will push out the overdue 1.9 as well. ETA before Saturday. The example in README is just copypasta from the included example, which I have updated some months ago. I'll make sure it builds. If something is profoundly wrong, we'll release a minor update regardless of semver. The only way of finding out is by releasing. Is that npm bug where index.js randomly isn't included fixed yet? |
I haven't seen the npm bug again, I think it should be good to go. Can always patch release if it happens again! Let me know if there's anything I can do to push this along and make sure it gets out into the wild ASAP. Also, re perl, it wasn't the first tool for the job, I considered, in the following order:
|
I should have a couple hours free to start working on this in six hours or so, then some more during Thursday evening, and then all of Friday if need be. I'll post a message here if I discover something tonight. Missing documentation has been the only holdup for the last couple of months, and now the docs are good enough for an initial release. As you said, we can always add more documentation in retrospect. |
@rvagg It would be nice to embed some more information from the V8 Embedder's Guide Such as https://developers.google.com/v8/get_started which has a part saying
Then there are |
done @ 2a97753 |
https://nodesource.com/blog/cpp-addons-for-nodejs-v4 <-- migration guide |
This is an open call for putting together the new documentation. The branch is located on this repository, so send pull requests directly here.