Repository navigation
Documenting node-addon-api functions and classes #758
Description
Activity
We discussed this in the N-API team meeting and the short answer is there is no good way that we know of to do what you want which we understood was JS documentation generated from C code.
@jschlight is going to do some investigation and comment as it was an area of interest for him.
Thanks for the response. If there were a way to document from c++, that would be ideal. In the near term, is it possible to create JSdoc documentation in the javascript binding script or test script that many of the examples include? Or do you think that maintaining synchronization between the c++ code and the javascript documentation in another file will be burdensome?
I think the basic issue is that the documentation needs to be written in terms that are meaningful to the JavaScript programmer. This implies a format like JSDoc. But in the case of native addons, the code is written in C++. It's possible to add JSDoc comments to the C++ code. But since the source code is in C++, the programmer does not get the benefit of IDE plugins that facilitate the creation of JSDoc comments from JavaScript code. The JSDoc comments must be manually created by the programmer from scratch. But once created, they provide really helpful information and are straightforward to maintain. What's not clear to me is if there is tooling that is able to extract the JSDoc comments from C++ code in order to get the documentation into a form that is accessible to the JavaScript programmer. This is something I'd like to look into.
But to answer your question, the JavaScript documentation needs to be manually created and maintained. I don't think it's a question of keeping the documentation synchronized because the examples seldom change. I think the question is, "Does the value of adding JSDoc comments outweigh the effort required to create them?" Perhaps it does.
The Node Mapnik project is embedding JSDoc comments in their NAN C++ files:
Here's the resulting generated documentation from these JSDoc comments:
http://mapnik.org/documentation/node-mapnik/3.6/
Apparently, the standard JSDoc project does not support parsing non-JavaScript files without some additional complexity. Node Mapnik is using documentation as an alternative.
So there is precedent for placing JSDoc comments in C++ binding files and generating documentation from them.
I'd like to research the idea of adding JSDoc-style comments to the examples the next time they're reviewed.
hi, I read the comments in this issue then I tried to add
documentationin a personal project, then I saw that c/c++ support (--polyglot option) was removed after version 4x (the current version is 13x), with apparent no plans to add support back.But I added version 4.x in a personal project and this is the result I saw:
- when running we see some warnings like this:
$ npm run docs (node:348692) Warning: Accessing non-existent property 'cat' of module exports inside circular dependency (Use `node --trace-warnings ...` to show where the warning was created) (node:348692) Warning: Accessing non-existent property 'cd' of module exports inside circular dependency (node:348692) Warning: Accessing non-existent property 'chmod' of module exports inside circular dependency (node:348692) Warning: Accessing non-existent property 'cp' of module exports inside circular dependency ...The resulting html (really basic docs from C code)
When I pass the mouse over a function in vscode:
This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.
This is still on my list. I'd like to keep this issue open until I've had the time to look at it.
This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.
This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.
@gotnone @jschlight @mhdawson This is in fact a major problem
Currently they are two solutions, both obsolete and not maintained anymore:
- https://github.com/yui/yuidoc, used by my project https://github.com/mmomtchev/node-gdal-async, last version is from 2016
- https://github.com/documentationjs, used by https://github.com/mapnik/node-mapnik which is still maintained but the C++ support got axed in 2017 in documentationjs/documentation@5b373ff
This is an important tool that is currently missing so if anyone is willing to contribute, I can spare the time necessary to bootstrap a new tool
Currently, IMHO, the best solution would be to develop a plugin/addon for https://github.com/documentationjs/documentation - everything that is need is a C++ parser/extractor
Any other suggestions?
yuidoc
+ all that is needed is to freshen up the package / update the dependencies - in fact it is already usable
- maintaining a full scale project that is somewhat obsoletedocumentation.js
+ well-maintained modern project
- C++ support is to be implemented from scrach@jschlight @gotnone @helio-frota @mhdawson
I have published the newdocumentation-polyglotplugin :
https://www.npmjs.com/package/documentation-polyglot
It requires a plugin framework indocumentationthat has yet to be merged, so one has to use it with my own@mmomtchev/documentationuntil it gets merged (hopefully it will)The first Node addon to use it is https://github.com/mmomtchev/exprtk.js - you can check it for an example
Is there a way to document the functions and classes exposed by a node-addon-api package? I could not find any examples containing JSdoc style comments. Searching this repository as well as the node-addon-examples repository for
/**provided no results. Thanks for looking into this.