Node.js 프로젝트 문서화

Node.js 프로젝트 문서화

---

현재 JSDoc Toolkit 을 사용하여 코드를 문서화하고 있지만 적합하지 않습니다. 즉, 네임 스페이스를 올바르게 설명하는 데 어려움을 겪는 것 같습니다. 각 파일에 두 개의 간단한 클래스가 있다고 가정합니다.

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및 로 출력 되며, 전역 범위에 모든 것이 없을 때 매우 필요합니다.Bardatabaselib.database

내가 던지는 해봤 @namespace database하고 @name database.Foo그것을, 그러나 그것은 좋은을 설정하지 않습니다.

JSDoc 출력을 더 적합하게 만드는 아이디어 나 Node.js에서 더 잘 작동하는 완전히 다른 도구가 있습니까? (내츄럴 닥스, JSDuck을 간략히 살펴보고 꽤 쓸모 없어 보이는 다른 몇 가지를 훑어 보았습니다 ...)

---

JSDoc은 JavaDoc의 포트입니다. 따라서 기본적으로 문서는 고전적인 OOP를 가정하고 JavaScript에 적합하지 않습니다.

개인적으로 소스 코드에 주석을 달기 위해 docco 를 사용하는 것이 좋습니다 . 밑줄 , 백본 , docco에 대한 예를 찾을 수 있습니다 .

docco의 좋은 대안은 식료품입니다.

실제 API 문서의 경우 개인적으로 주석에서 자동 생성 된 문서가 JavaScript에서 작동하지 않는다는 것을 발견하고 API 문서를 직접 작성하는 것이 좋습니다.

예는 밑줄 API , Express API , nodejs API , socket.io 문서입니다.

유사한 StackOverFlow 질문

• 자바 스크립트 문서 생성

---

YUIDoc 은 Javadoc 및 Doxygen과 같은 도구와 유사한 구문을 사용하여 소스의 주석에서 API 문서를 생성하는 Node.js 애플리케이션입니다. YUIDoc은 다음을 제공합니다.

• 실시간 미리보기. YUIDoc에는 독립형 문서 서버가 포함되어있어 문서를 작성할 때 미리보기가 간단합니다.
• 최신 마크 업. YUIDoc의 생성 된 문서는 JavaScript를 실행할 수없는 스파이더 및 기타 에이전트에 대한 실제 URL과 우아한 폴 백이 포함 된 매력적이고 기능적인 웹 애플리케이션입니다.
• 광범위한 언어 지원. YUIDoc은 원래 YUI 프로젝트 용으로 설계되었지만 특정 라이브러리 나 프로그래밍 언어와 관련이 없습니다. / * * / 주석 블록을 지원하는 모든 언어와 함께 사용할 수 있습니다.

---

참고 : Dox 는 더 이상 HTML을 출력하지 않지만 구문 분석 된 코드를 설명하는 JSON blob입니다. 이것은 아래 코드가 더 이상 잘 작동하지 않음을 의미합니다.

우리는 당분간 Dox 를 사용하게되었습니다. 그것은 같은 많은입니다 docco Raynos 언급 것을,하지만, 출력 한 비트 HTML 파일에 모든 슬로우하는.

우리는 이것을 우리에게 해킹했습니다 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" $^ > $@

이것은 지금까지 만들어진 문서 중 가장 예쁘거나 가장 효율적인 문서는 아니지만 (그리고 dox에는 몇 가지 사소한 버그가 있습니다)-적어도 사소한 프로젝트에서는 잘 작동합니다.

---

Sorry, I was not on StackExchange a year ago, but I believe the answer to your original question is to use the @memberOf tag:

/** @namespace */
database = {};

/**
 * @class
 * @memberOf database
 */
function Foo() { ... };

http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf

This tag may or may not have existed when you asked your question.

---

Found a really nice solution for the problem: doxx.

It uses dox as mentioned above and converts this to nice HTML afterwards. Has a nice usage and worked great for me.

https://github.com/FGRibreau/doxx

---

I work with JSDoc and is very efficient, in addition to easy, but when projects have many alternate libraries are quite complicated development. I found Groc a very good tool based on Docco and works with other languages like: Python, Ruby, C + +, among others...

Furthermore Groc working with Markdown in GitHub which can be much more efficient when working with git as version control. Further helps assemble pages for publishing on GitHub.

You can also use the task manager GruntJS through grunt-groc example:

Install package:

npm install grunt-groc --save-dev

configure in your task file:

grunt.loadNpmTasks('grunt-groc');

And the config task:

// Project configuration.
grunt.initConfig({
   groc: {
    coffeescript: [
       "coffee/*.coffee", "README.md"
   ],
    options: {
       "out": "doc/"
   }
 }

});

For run task:

grunt.registerTask('doc', ['groc'])

참고URL : https://stackoverflow.com/questions/6096649/documenting-node-js-projects