Doccoは、CoffeeScriptにコメントをつけてドキュメントを出力できるパッケージです。コードとコメントを左右に表示されるスタイルです。コメントにはMarkdownが使えます。
インストール
インストールはnpm。追加でPygmentsが必要です。
$ npm install -g docco $ sudo easy_install Pygments
使い方
先日のエントリーで紹介したブログアプリCoffee-Boxを例にコメントを書くとこうなります。
(CoffeeBoxの紹介は 『Node.js「脱」初心者！CoffeeBoxでブログの作り方を学ぼう！』を参照してください）
# ***server.coffee*** は、Coffee-Boxのエントリーポイントです。
# [express](http://expressjs.com/)を読み込みます。
express = require 'express'
# Webサーバを生成します。
app = module.exports = express.createServer()
# config/configを読み込みます。
require('./config/config') app
# config/routesを読み込みます。
require('./config/routes') app
# Webサーバを起動します。
app.listen 3000
# サーバが起動したことを出力します。
console.log "coffee-box server listening on port #{app.address().port} " +
"in #{app.settings.env} mode"
ドキュメントを出力してみます。docsディレクトリが必要なので作成します。
$ mkdir docs $ docco server.coffee docco: server.coffee -> docs/server.html
左側にコメントに書いた内容が、右側にコードが表示されます。比較しながら読める点が新鮮です。
少し本格的にCoffeeBoxのconfig/config.coffeeにコメントを書いていきます。
# **config.coffee**では、[Coffee-Box](https://github.com/qiao/coffee-box)のWebサーバを設定します。
# [express](http://expressjs.com/)を読み込みます。
express = require 'express'
# [connect-assets](https://github.com/TrevorBurnham/connect-assets)を読み込みます。
assets = require 'connect-assets'
# [mongoose](https://github.com/LearnBoost/mongoose)を読み込みます。
mongoose = require 'mongoose'
# lib/require_dirを読み込んで、オブジェクトとして保持します。
{requireDir} = require '../lib/require_dir'
# ```ROOT_DIR```を読み込みます。
# ```#{hoge}```は、CoffeeScriptの String Interpolation（文字列挿入）です。
# ```__dirname```は、Nodeが起動したディレクトリパスを示す定数です。
ROOT_DIR = "#{__dirname}/.."
# Webサーバを設定します。
#
# 第1引数にexpressのWebサーバappを指定します。
module.exports = (app) ->
app.configure ->
# アプリケーションのversionを設定します。versionの情報は、[package.json](../package.json)に記述します。
app.set 'version', require("#{ROOT_DIR}/package.json").version
# [site.json](../config/site.json)に記述されたkeyとvalueをすべて設定します。
# CoffeeSciprtの for ... of 構文です。
# 例えば sitename というkeyに、**Name of your site**というvalueがappに設定されます。
app.set k, v for k, v of require("#{ROOT_DIR}/config/site.json")
# libディレクトリをutilsとして設定します。
app.set 'utils', requireDir("#{ROOT_DIR}/lib")
# app/helpersディレクトリをhelpersとして設定します。
app.set 'helpers', requireDir("#{ROOT_DIR}/app/helpers")
# app/modelsディレクトリをmodelsとして設定します。
app.set 'models', requireDir("#{ROOT_DIR}/app/models")
# app/controllersディレクトリをcontrollersGetterとして設定します。
app.set 'controllersGetter', requireDir("#{ROOT_DIR}/app/controllers")
# expressのviewsディレクトリをapp/viewsに設定します。
app.set 'views', "#{ROOT_DIR}/app/views"
# テンプレートエンジンを[jade](http://jade-lang.com/)に設定します。
app.set 'view engine', 'jade'
# ビューのオプションとして、layoutを設定します。
app.set 'view options', layout: "#{ROOT_DIR}/app/views/layouts/layout"
# expressのloggerを使います。
# **loggerはミドルウェアで一番最初に設定すること**
app.use express.logger('dev')
# リクエストの```req.body```を読み込めるように設定します。
app.use express.bodyParser()
# HTTPのPUTやDELETEなどのメソッドをオーバライドできるように設定します。
# **この設定はbodyParserの前にすること**
app.use express.methodOverride()
# cookieを使えるようにします。
app.use express.cookieParser()
# sessionを設定します。
# secretキーに```settings.secretKey```を設定します。
app.use express.session(secret: app.settings.secretKey)
# [connect-assets](https://github.com/TrevorBurnham/connect-assets)を使います。
app.use assets(src: 'app/assets', build: true, detectChanges: false, buildDir: false)
# staticディレクトリをpublicに設定します。
# このディレクトリにはJavascript, CSS, HTMLなどの静的ファイルを格納します。
app.use express.static("#{ROOT_DIR}/public")
# routerを設定します。
# app.routerは、[server.coffee](server.html)で設定されています。
app.use app.router
# helpersを設定します。
# helpersはさっき設定しました。
app.helpers app.settings.helpers
# [express-messages](https://github.com/visionmedia/express-messages) をダイナミックヘルパに設定します。
app.dynamicHelpers messages: require('express-messages')
# session をダイナミックヘルパに設定します。
app.dynamicHelpers session: (req, res) -> req.session
# 開発用の設定を指定します。
app.configure 'development', ->
app.use express.errorHandler(dumpException: true, showStack: true)
# 製品用の設定を指定します。
app.configure 'production', ->
app.use express.errorHandler()
# MongoDbに接続します。
# 接続先は```app.settings.dbpath```です。
# errが発生した場合、コンソールにエラー出力し、Coffee-Boxを終了します。
mongoose.connect app.settings.dbpath, (err) ->
if err
console.error err
process.exit()
これを出力した結果が以下の画像です。
Doccoはコードリーディングに最適
Doccoは、左右にドキュメントとコードを並べるスタイルが最大の特徴です。「何をしているかをコードと比較できる」点でコードを理解しやすいと感じます。リーディングしながらコメントを書いていき出力を繰り返すと、「どこまで自分が理解しているか」という進捗にもDoccoが使えます。また、Markdown形式でリンクや強調などの表現もできるので「着目している点や参考にしたリンク」も加筆できます。キレイなドキュメントで出力されるのでモチベーションも保てそうです。お試しあれ。
0 件のコメント:
コメントを投稿