GAS|JSDoc コメントを書く|Javascript|Google Apps Script|開発裏話
「マンガポスト日本版」では、Google ドライブ内に保存している「コミックス発売日情報」を参照して、その日付を基に毎日自動配信(ツイート)しています。
一部の処理は、GAS の各プロジェクトで共有できるように、「ライブラリ」として作成しています。
特に、GAS で「ライブラリ」を作成するのであれば、JSDoc コメントを正しく書くべきです。以下のガイドに記載の通り、ライブラリの各ファンクションを正しくオートコンプリート(自動補完)させる為、自動生成ドキュメントを正しく表示させる為です。
Best practices
Here are some guidelines to follow when writing a library:
...
4. If you want your library users to make use of Script Editor autocomplete and the automatically generated documentation, you must have JSDoc-style documentation for all your functions.
★ Only the @param and @return annotations are currently supported.
例えば、自作ライブラリ「ISBNValidator」の各ファンクションに、JSDoc コメントを以下のように正しく記述しました。上記ガイドの通り、アノテーションは「@param」「@return」しか現在はサポートされていません。
/**
* Check the code is either a valid ISBN-10 or ISBN-13 code.
*
* @param {string} code The code to validate.
* @return {boolean} <code>true</code> if a valid ISBN-10 or
* ISBN-13 code, otherwise <code>false</code>.
*/
function isValid(code) {
return (isValidISBN13(code) || isValidISBN10(code));
}
このライブラリを公開し、別のプロジェクトで「ISBNValidator」を実装すると、以下の通り、オートコンプリート(自動補完)が正しく表示されます。
JSDoc コメントを正しく書かなければ、このように引数と戻り値の「型」は正しく表示されません(引数は Object に、戻り値は void になってしまう)。ですので、開発の混乱を避けるためにも、JSDoc コメントは必須のものでしょう。
また、ライブラリを公開すると、自動で WEB ドキュメント(リファレンス)が生成されます。以下の通り、説明文など、JSDoc コメントがそのまま表示されます。
マンガポスト日本版
マンガポスト日本版の Twitter 公式アカウントです。
漫画(まんが)・コミックの新刊情報を毎日配信中!
コーヒーブレイク
桶屋風太は中学2年生。平凡な中学生生活だったはずが額に大きな傷のある美少女の転入生・石神鉱子の出現によって一変する事に!
この記事が気に入ったらサポートをしてみませんか?