Menu
I'm currently using JSDoc Toolkit to document my code, but it doesn't quite fit - namely, it seem to struggle with describing namespaces properly. Say you have two simple classes in each their files:
lib/database/foo.js:
/** @class */ function Foo(...) {...} /** @function ... */ Foo.prototype.init(..., cb) { return cb(null, ...); }; module.exports = foo; And then something inherited lib/database/bar.js:
var Foo = require('./foo'); /** * @class * @augments Foo */ function Bar(....) {...} util.inherits(Bar, Foo); Bar.prototype.moreInit(..., cb) { return cb(null, ...); }; In the generated documentation, this is output simply as Foo and Bar, without the leading database (or lib.database), which are quite necessary when you don't have everything in a global scope.
I've tried throwing @namespace database and @name database.Foo at it, but it doesn't turn out nice.
Any ideas for making JSDoc output something more suitable, or some entirely different tool that works better with Node.js? (I looked briefly at Natural Docs, JSDuck and breezed over quite a few others that looked quite obsolete...)
715
writeFileSync() to write data in files. The latter is a synchronous method for writing data in files. fs. writeFileSync() is a synchronous method, and synchronous code blocks the execution of program. Hence, it is preferred and good practice to use asynchronous methods in Node.
The createWriteStream() method is an inbuilt application programming interface of fs module which allows to quickly make a writable stream for the purpose of writing data to a file. This method may be a smarter option compared to methods like fs. writeFile when it comes to very large amounts of data.
In fs. readFile() method, we can read a file in a non-blocking asynchronous way, but in fs. readFileSync() method, we can read files in a synchronous way, i.e. we are telling node. js to block other parallel process and do the current file reading process.
JSDoc is a port of JavaDoc. So basically the documentation assumes classical OOP and that's not suited to JavaScript.
Personally I would recommend using docco to annotate your source code. Examples of it can be found for underscore, backbone, docco.
A good alternative to docco is groc
As for an actual API documentation, I personally find auto generated documentation from comments just does not work for JavaScript and recommend you hand-write your API documentation.
Examples would be underscore API, Express API, nodejs API, socket.io docs
Similar StackOverFlow questions
51
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
