63

私は現在JSDoc Toolkitを使用してコードを文書化していますが、うまく適合しません。つまり、名前空間を適切に記述するのに苦労しているようです。それぞれのファイルに 2 つの単純なクラスがあるとします。

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, ...); };

生成されたドキュメントでは、これは単純にFooandとして出力されBar、先頭のdatabase(or lib.database) は省略されます。これは、グローバル スコープにすべてが含まれていない場合に非常に必要です。

投げてみましたが@namespace database、うまくいき@name database.Fooません。

JSDoc 出力をより適切なものにするためのアイデア、または Node.js でより適切に機能するまったく異なるツールを作成するためのアイデアはありますか? （私はNatural Docs、JSDuckを簡単に見て、かなり時代遅れに見える他のかなりの数を簡単に調べました...）

4

6 に答える 6

71

JSDoc は JavaDoc のポートです。したがって、基本的にドキュメントは従来の OOP を想定しており、JavaScript には適していません。

個人的には、doccoを使用してソース コードに注釈を付けることをお勧めします。その例は、アンダースコア、バックボーン、ドコで見つけることができます。

doccoの優れた代替手段はgroc です

実際の API ドキュメントに関しては、コメントから自動生成されたドキュメントは JavaScript では機能しないことが個人的にわかっているため、API ドキュメントを手書きすることをお勧めします。

例としては、underscore API、Express API、nodejs API、socket.io docsがあります。

同様の StackOverFlow の質問

于 2011-05-23T11:45:09.563 に答える
17

YUIDocは、JavadocやDoxygenなどのツールと同様の構文を使用して、ソース内のコメントからAPIドキュメントを生成するNode.jsアプリケーションです。YUIDocは以下を提供します：

  • ライブプレビュー。YUIDocにはスタンドアロンのドキュメントサーバーが含まれているため、作成時にドキュメントを簡単にプレビューできます。
  • 現代のマークアップ。YUIDocが生成したドキュメントは、JavaScriptを実行できないスパイダーやその他のエージェント向けの実際のURLと適切なフォールバックを備えた魅力的で機能的なWebアプリケーションです。
  • 幅広い言語サポート。YUIDocは元々YUIプロジェクト用に設計されましたが、特定のライブラリやプログラミング言語に関連付けられていません。/ **/コメントブロックをサポートする任意の言語で使用できます。
于 2012-10-08T00:30:21.053 に答える
12

注: Doxは HTML を出力しなくなりましたが、解析されたコードを記述する JSON のブロブを出力します。これは、以下のコードがうまく機能しないことを意味します...

今のところDoxを使用することになりました。Raynos が言及しているのは docco によく似ていますが、出力用にすべてを 1 ビットの HTML ファイルにまとめています。

makefileこれをsにハッキングしました。

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 にはかなりの数のマイナーなバグがあります)。

于 2011-08-09T11:47:48.950 に答える
5

申し訳ありませんが、私は 1 年前に StackExchange に参加していませんでしたが、元の質問に対する答えは @memberOf タグを使用することだと思います。

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

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

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

このタグは、質問した時点で存在していた場合と存在していなかった場合があります。

于 2012-03-13T15:53:48.847 に答える