JSのコメントからmarkdownファイルを生成するgulpプラグイン作った

コメントからドキュメント生成するのは結構あるけど、単純にそのままmarkdownとして出力するものは探したけどなかったので作った。（あるぞという場合は教えてくださいm(_ _)m すごくありそうな気がする...）

インストール

$ npm i --save-dev gulp gulp-comment2md

使い方

/*md
 * Title
 * =====
 * 
 * - one
 * - two
 * - three
 */
function hello () {
  console.log('hello!!');
}

↑のように/*mdもしくは/*markdownで始まるブロックコメントを書く。

var gulp = require('gulp');
var comment2md = require('gulp-comment2md');

gulp.task('markdown', function () {
  return gulp.src('src/**/*.js')
    .pipe(comment2md())
    .pipe(gulp.dest('doc/'));
});

このようなtaskを書いて実行すると、src/hello.jsの場合、doc/hello.mdという感じで出力する。
出力ファイル名を変えたい場合は、引数に文字列か、関数を渡すことで変更できる。

comment2md('new-name.md') // new-name.mdで出力

// `file`はvinyl
// https://github.com/wearefractal/vinyl
comment2md(function (file) {
  return 'new-name.md'; // new-name.mdで出力
})

開発・テスト

• babelを使ってES6で書いた
  • 参考：ライブラリをES6で書いて公開する所から始めよう
• eslint使った。
  • .eslintrcのparserにbabel-eslintを指定
  • 初めはルール一覧を見ながら書いていたが、かなり辛かったので、デフォルトでeslintを実行して、エラーの出る部分を修正しながらeslintrcを書いた
    • 抜けがありそうなので、いつか書き直したい
• テストはmocha + espower-babel
• streamのテストはgulp-concatを参考に、stream-assertを使って書いた。
• gulp使おうか迷ったけど、結局npm scriptsで頑張った。

バグや要望があれば、issueにくださいなー