JavaScriptこんにちは。会員事業部の丸山@h13i32maruです*1。ソフトウェアのドキュメント(マニュアル)を書くには色々なツールや方法があります。JavaScriptの場合はJSDocというドキュメンテーションツールがデファクトスタンダードです。JSDocの競合として新しいツールが登場したり、JSDoc自体もバージョンアップしたりしています。本記事ではそうした新しいツールの一つであるESDocを紹介します。ESDocとは?ESDocとは私が2015年4月から開発を行っている、JavaScript(ES2015)向けの良いドキュメントを作るためのドキュメンテーションツールです。Lonlyplanet/rizzo-nextなどのプロダクトに採用され始めています。ESDoc自身もESDocでドキュメントが書かれてています。ESDocで作成されたESDocのドキュメント良いドキュメントとは?本来なら、良いドキュメントとはどういうものなのかを解説したいのですが、そのためには「ドキュメントとはそもそもどういうものなのか?」「ドキュメントはなぜ書くのか?」「ドキュメントはどういう構造をしているのか?」「ドキュメントの評価はどうすればよいのか?」などについて解説する必要があります。このブログはそれを書くには狭すぎるため*2、今回は割愛します。Explorerにて紹介しています。Explorerは多数の著者による共著になっており、ESDoc以外にもWebの最先端の話が収録された書籍になりますので、興味のある方は是非御覧ください。Explorerの表紙どうやって良いドキュメントを作るのか?ESDocの基本的な動作はJSDocやJavadocと同じくソースコード中に特定の記法で書かれたコメント(ドキュメントコメント)を元にドキュメントを作成するツールです。b;}しかし、JSDocやJavadocはソフトウェアのAPIリファレンスを作成することを目的としていますが、ESDocの目的はそれだけではありません。ESDocの目的はソフトウェアを使用するために必要な情報全般を含んだドキュメントを作成することです。ここでいうドキュメントとは一般的にマニュアルと呼ばれ、インストール方法、チュートリアル、サンプル、変更履歴などの情報をまとめたものを指します。ESDocは良いドキュメントを作成するために次のような特徴的な機能を提供しています。組み込み検索ホスティング以降ではこれらの機能を簡単に紹介していきます。マニュアルの統合マニュアルの統合機能はMarkdownで書かれた複数のファイルをドキュメントに組み込むという機能です。これによって、インストール方法、チュートリアル、サンプル、変更履歴など、ドキュメント(マニュアル)に必要な内容を包括的に作成できます。マニュアルとして組み込まれたチュートリアルカバレッジカバレッジ機能とはテストカバレッジと同じように、ドキュメントが書かれるべきところ(クラスやメソッド)にどれだけ書かれているかを確認する機能です。ドキュメントのカバレッジを可視化することで継続的にドキュメントを保守するモチベーションに繋がると考えています。このカバレッジ機能についてひとつ注意してほしいことは、かならずしもカバレッジ100%を目指す必要はないということです。ドキュメントの継続性を改善するためとして、どの程度のカバレッジが必要かは各開発者の判断にお任せします。ドキュメントを書くべき箇所(350)と実際に書かれている箇所(323)全体のカバレッジと各ファイルごとのカバレッジLintLint機能とはドキュメントがコードに対して間違っていないかを検証するための機能です。ドキュメントとコードの不一致を検証するのであって、ドキュメント自体が正しいかどうかを検証できるものではありません。今のところ、このLintが対象にするのはメソッドのシグネチャとドキュメントが一致しているかどうかだけです。ドキュメントコメントが書かれていないコードからもそのコードから分かる情報をつかってなるべくドキュメントを生成するというものです。次のようにドキュメントが一切書いていないソースコードの場合でも「Class構文によるクラスと継承」「デフォルト引数による仮引数の型」「return文による戻り値の存在」「テンプレートリテラルによる文字列型」を解析することで、ある程度ドキュメントを作成することができます。}}テストコードの統合テストコードの統合機能とはテストコード自体も有益なドキュメントと考え、テストコードとテスト対象を関連付けてドキュメントを生成するというものです。テストコードとテスト対象を次のように@testを使って関連付けると、生成されたFooクラスのドキュメントにはテストコードへのリンクが、テストコードの一覧にはテスト対象へのリンクが自動的に追加されます。組み込み検索機能とはその名前のとおり、ドキュメント内を検索できる機能です。この組み込み検索機能はJavaScriptだけで実装されているため、サーバ側の実装は一切不要です。静的ファイルとしてWebサーバで配信する、もしくはローカルのファイルをブラウザで直接開いて検索できます。ドキュメント内を任意のキーワードで検索ホスティングドキュメントを作成したあと、どこかで公開して誰でも閲覧できるようにする必要があります。そこで手軽にドキュメントを公開できる仕組みとして、ESDoc専用のホスティングサービスを提供しています。このホスティングサービスはESDocを使用しているGitHubのリポジトリURLを登録するだけで利用できます。ホスティングサービスに登録されているドキュメントホスティングサービスへの登録方法おわりにソフトウェアはコードとテスト、そしてドキュメントから成り立つものです。コードとテストはたくさんの解説書や議論がありますが、ドキュメントはそうではありません。そのためドキュメンテーションツールもあまり進化していません。そのような状況に何かしら一石を投じたいと思い、ESDocを開発しています。これを期にドキュメントについて興味を持たれた方がいらっしゃれば是非、ドキュメントについても考えてみてください。良いドキュメントはより良いソフトウェアを作ります。コスト最適化についてご紹...2019-06-25SwiftUIで使用されているSwift5.1の新機能こんにちは。技術部の遠藤(mame)です。Challenge今年1月に入社した技術部の笹田です。インタプリタの開発...2014-11-19Infratasterでリバースプロキシのテストをするインフラ部の荒井(@ryot_a_rai)です。使ったセキュリティログ検索基盤の構築サービス特性にあった検索システムの設計戦略クックパッド採用説明会「クックパッドはサービスの作り手を採用したいんです。/*}*/スターをつけました引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。