web-dev-qa-db-ja.com

Node.jsプロジェクトの文書化

現在、コードを文書化するために 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, ...); };

生成されたドキュメントでは、これは単にFooおよびBarとして出力されます。先頭のdatabase（またはlib.database）はありません。 tすべてをグローバルスコープに含める。

@namespace databaseと@name database.Fooを投げてみましたが、ナイスにはなりません。

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

documentationnode.jscode-documentation
58
Morten Siebuhr

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

とりあえず Dox を使用しました。 docco によく似ていますが、Raynosが言及していますが、出力用にすべてを1ビットのHTMLファイルに入れています。

これをmakefilesにハッキングしました：

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にはいくつかのマイナーなバグがあります）。しかし、少なくともマイナーなプロジェクトではかなりうまくいきます。

12
Morten Siebuhr

JSDocはJavaDocの移植です。そのため、基本的にドキュメントは古典的なOOPを想定しており、JavaScriptには適していません。

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

Doccoに代わる適切な方法は groc です

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

例は アンダースコアAPI 、 Express API 、 nodejs API 、 socket.io docs

StackOverFlowに関する同様の質問

69
Raynos

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

  • ライブプレビュー。 YUIDocにはスタンドアロンドキュメントサーバーが含まれているため、作成中にドキュメントをプレビューするのは簡単です。
  • モダンなマークアップ。 YUIDocが生成するドキュメントは、JavaScriptを実行できないスパイダーやその他のエージェントのための実際のURLと優雅なフォールバックを備えた魅力的で機能的なWebアプリケーションです。
  • 幅広い言語サポート。 YUIDocは元々YUIプロジェクト用に設計されたものですが、特定のライブラリやプログラミング言語とは結びついていません。/* * /コメントブロックをサポートする任意の言語で使用できます。
17
Bill Gao

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

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

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

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

このタグは、質問したときに存在する場合と存在しない場合があります。

5
John Freeman

問題に対する本当に素晴らしい解決策を見つけました：doxx。

上記のようにdoxを使用し、その後これをNice HTMLに変換します。すてきな使い方をしていて、私にとってはうまくいきました。

https://github.com/FGRibreau/doxx

3
Phil

私はJSDocを使用しており、簡単に加えて非常に効率的ですが、プロジェクトに多数の代替ライブラリがある場合、開発は非常に複雑になります。 Groc はDoccoに基づいた非常に優れたツールであり、Python、Ruby、C++などのような他の言語で動作します...

さらに、GitHubでMarkdownを使用するGrocは、バージョン管理としてgitを使用する場合にはるかに効率的です。さらに、GitHubで公開するためのページを組み立てるのに役立ちます。

_grunt-groc_の例でタスクマネージャーGruntJSを使用することもできます。

パッケージをインストールします。

_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'])

2
alejo8591