Docs: C/C++ Links to node-postgress which is NOT v0.6.x compatible yet

[ddopson]

this seems very broken. Pretty much the only documentation for writing a native module is a link to node-postgress. ..... which still uses the EventEmitter class that doesn't exist in node v0.6.x.

Either get node-postgress needs to be ported to node v0.6.x, or we should pick a new example.

[ddopson]

http://nodejs.org/docs/latest/api/addons.html ...

"For the moment, that is all the documentation on addons. Please see https://github.com/ry/node_postgres for a real example."

[ddopson]

https://github.com/ry/node_postgres/blob/master/binding.cc hasn't been update since 2010! It has a 0% chance of compiling on node v0.6.x since the native EventEmitter class no longer even exists!

[ddopson]

I did a bunch of work on https://github.com/ddopson/node-zookeeper to update it to v0.6.x. I'm not sure I'd say it's a shining example of the pattern for building a node module, but it does work.

[ddopson]

https://github.com/astro/node-expat was updated in Aug 2011 (~4 mo ago) for v0.5.x compat. This would also be acceptable.

[defunctzombie]

I gave a presentation on node c++ modules not too long ago: https://github.com/shtylman/node-presentation (and the subsequent gh-pages branch: http://shtylman.github.com/node-presentation/#1). If that seems like generally good stuff I would be happy to provide documentation updates based on it.

[bnoordhuis]

@shtylman: Yes, please. Can you stress in your async example that the work callback cannot use anything from or call into V8?

[defunctzombie]

@bnoordhuis Will do. Do you want the examples written up all on one page as it is now? Or broken up into sections?

[bnoordhuis]

Do you want the examples written up all on one page as it is now?

One page is fine but can you make it less presentation-y than http://shtylman.github.com/node-presentation/ ? :)

[defunctzombie]

@bnoordhuis yea. I will just move the relevant code and descriptions into the docs page with no "presentation-y" aspects :)

[ddopson]

If we are going to get some real attention on this, I'd be glad to contribute my own linguistic talents.

Ideally, a discussion of native modules would cover the following:

• Trivial Example with a sync function (just to show module structure, wscript, etc. all the trappings)
• Best Practice example that implements a class and an async method. This should serve as the template for most modules
• Primatives - making an object, making a function. internal properties, etc. cover the basics of V8 and then link to the V8 docs. (this is "how to create stuff in native code that can be called from JS-land")
• Interacting with JS code - calling a JS function, getting a property from an object, etc. accessor functions.
• Discussion of interacting with the V8 event loop (summarize the basics, then link to the V8 docs)
• Links to other example modules with ~1 sentence mentioning something unique about the module (eg, "example of a module that manipulates the v8 machine state")
• Appendix: Discussion of the v0.4.x-v0.6.x EventEmitter change with a quick example of how to fix it
• Appendix: next backcompat breaking change. eg, the try/require/catch pattern needed to address the change from "build/default" ==> "build/Release" as the default build output dir for node-waf
• Appendix: next most painful back compat breaking change. any contenders here?

[bnoordhuis]

@arturadib is working on some great add-on documentation in #2390. Let's continue the discussion there.