documentation - नोड.जेएस परियोजनाओं को दस्तावेज
node.js code-documentation (4)
मैं वर्तमान में अपने कोड को दस्तावेज़ित करने के लिए जेएसडीओसी टूलकिट का उपयोग कर रहा हूं, लेकिन यह काफी फिट नहीं है - यानी, यह नामस्थानों का सही वर्णन करने के साथ संघर्ष करना प्रतीत होता है। मान लें कि आपके पास प्रत्येक फाइल में दो साधारण कक्षाएं हैं:
lib/database/foo.js :
/** @class */
function Foo(...) {...}
/** @function ... */
Foo.prototype.init(..., cb) { return cb(null, ...); };
module.exports = foo;
और फिर कुछ विरासत में मिली lib/database/bar.js :
var Foo = require('./foo');
/**
* @class
* @augments Foo
*/
function Bar(....) {...}
util.inherits(Bar, Foo);
Bar.prototype.moreInit(..., cb) { return cb(null, ...); };
जेनरेट किए गए प्रलेखन में, यह आउटपुट केवल Foo और Bar , बिना अग्रणी database (या lib.database ) के, जो कि आपके पास वैश्विक दायरे में सबकुछ नहीं है, जो काफी आवश्यक हैं।
मैंने @namespace database और @name database.Foo फेंकने की कोशिश की है। इस पर @namespace database , लेकिन यह अच्छा नहीं है।
JSDoc आउटपुट को और अधिक उपयुक्त बनाने के लिए कोई विचार, या कुछ पूरी तरह से अलग उपकरण जो Node.js के साथ बेहतर काम करता है? (मैंने संक्षेप में प्राकृतिक डॉक्स, जेएसडीक पर देखा और काफी कुछ अप्रचलित दिखने वाले कुछ अन्य लोगों पर झुका हुआ ...)
नोट: Dox अब HTML आउटपुट नहीं करता है, लेकिन पार्स कोड का वर्णन करने वाले JSON का ब्लॉब। इसका मतलब है कि नीचे दिया गया कोड अब भी बहुत अच्छी तरह से काम नहीं करता है ...
हम अभी के लिए Dox का उपयोग कर समाप्त हो गए। यह docco तरह है, कि रेनोस का उल्लेख है, लेकिन आउटपुट के लिए एक बिट एचटीएमएल फाइल में यह सब कुछ फेंकता है।
हमने इसे हमारे makefile में हैक किया है:
JS_FILES := $(shell find lib/ -type f -name \*.js | grep -v 3rdparty)
#Add node_modules/*/bin/ to path:
#Ugly 'subst' hack: Check the Make Manual section 8.1 - Function Call Syntax
NPM_BINS:=$(subst bin node,bin:node,$(shell find node_modules/ -name bin -type d))
ifneq ($(NPM_BINS),)
PATH:=${NPM_BINS}:${PATH}
endif
.PHONY: doc lint test
doc: doc/index.html
doc/index.html: $(JS_FILES)
@mkdir -p doc
dox --title "Project Name" $^ > [email protected]
यह अब तक का सबसे सुंदर या सबसे कुशल दस्तावेज नहीं है (और डॉक्स में कुछ मामूली बग हैं) - लेकिन मुझे लगता है कि कम से कम मामूली परियोजनाओं के लिए यह काम अच्छी तरह से काम करता है।
क्षमा करें, मैं एक साल पहले स्टैक एक्सचेंज पर नहीं था, लेकिन मेरा मानना है कि आपके मूल प्रश्न का उत्तर @memberOf टैग का उपयोग करना है:
/** @namespace */
database = {};
/**
* @class
* @memberOf database
*/
function Foo() { ... };
http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf
जब आप अपने प्रश्न पूछते हैं तो यह टैग मौजूद हो सकता है या नहीं भी हो सकता है।
मैं जेएसडीओसी के साथ काम करता हूं और आसान के अलावा, बहुत ही कुशल है, लेकिन जब परियोजनाओं में कई वैकल्पिक पुस्तकालय काफी जटिल विकास होते हैं। मैंने Docco को Docco पर आधारित एक बहुत अच्छा टूल पाया और अन्य भाषाओं के साथ काम करता है जैसे: पायथन, रूबी, सी + +, दूसरों के बीच ...
इसके अलावा Groc साथ काम कर रहे ग्रोक जो संस्करण नियंत्रण के रूप में गिट के साथ काम करते समय अधिक कुशल हो सकते हैं। आगे गिटहब पर प्रकाशन के लिए पृष्ठों को इकट्ठा करने में मदद करता है।
आप grunt-groc उदाहरण के माध्यम से टास्क मैनेजर grunt-groc भी उपयोग कर सकते हैं:
पैकेज स्थापित करे:
npm install grunt-groc --save-dev
अपनी कार्य फ़ाइल में कॉन्फ़िगर करें:
grunt.loadNpmTasks('grunt-groc');
और विन्यास कार्य:
// Project configuration.
grunt.initConfig({
groc: {
coffeescript: [
"coffee/*.coffee", "README.md"
],
options: {
"out": "doc/"
}
}
});
रन कार्य के लिए:
grunt.registerTask('doc', ['groc'])
समस्या के लिए वास्तव में एक अच्छा समाधान मिला: Doxx।
यह उपरोक्त वर्णित डॉक्स का उपयोग करता है और बाद में इसे अच्छे HTML में परिवर्तित करता है। एक अच्छा उपयोग है और मेरे लिए बहुत अच्छा काम किया है।