@google/clasp/docs.js

Develop Apps Script Projects locally

/**
 * Generates the How To section of the docs.
 * Ensures the code for clasp commands is well documented.
 * @todo Generate a list of commands for the beginning of the README.
 */
var fs = require('fs');
var parseComments = require('parse-comments');
var extract = require('extract-comments');
var file = fs.readFileSync('./index.ts').toString();
var ucfirst = require('ucfirst');
// The README will be a concatenation of lines in this variable.
var readme = [
    '## How To...',
];
// Remove first line (#!/usr/bin/env node)
var fileLines = file.split('\n');
fileLines.splice(0, 1);
var fileWithoutFirstLine = fileLines.join('\n');
// Extract JSDoc comments out of our file.
var comments = extract(fileWithoutFirstLine);
for (var _i = 0, comments_1 = comments; _i < comments_1.length; _i++) {
    var command = comments_1[_i];
    // To use the parseComments module, complete the stripped comment.
    var comment = "/*" + command.raw + "*/";
    var claspCommand = parseComments(comment)[0];
    // Only print valid commands.
    if (claspCommand && claspCommand.description && claspCommand.name) {
        readme.push('');
        readme.push("### " + ucfirst(claspCommand.name));
        readme.push('');
        readme.push(claspCommand.description);
        // Parameters (@param)
        if (claspCommand.params && claspCommand.params.length) {
            readme.push('');
            readme.push('#### Options\n');
            claspCommand.params.map(function (param) {
                var isOptional = param.type.indexOf('?') !== -1;
                // readme.push(JSON.stringify(param));
                var paramName = param.parent || param.description.split(' ')[0];
                if (isOptional) {
                    readme.push([
                        // `\`clasp ${claspCommand.name}`,
                        "- `" + paramName + "`:",
                        param.description,
                    ].join(' '));
                }
                else {
                    // Required parameters descriptions aren't parsed by parse-comments. Parse them manually.
                    readme.push([
                        // `\`clasp ${claspCommand.name}`,
                        "- `" + paramName + "`:",
                        param.description,
                    ].join(' '));
                }
            });
        }
        // Examples (@example)
        if (claspCommand.example) {
            readme.push('');
            readme.push('#### Examples\n');
            var examples = claspCommand.example.split(',');
            examples.map(function (example) {
                readme.push("- `clasp " + example + "`");
            });
        }
        // Extra Description (@desc)
        if (claspCommand.desc) {
            readme.push('');
            var lines = claspCommand.desc.split('-');
            lines.map(function (line, i) {
                var value = '';
                if (i)
                    value += '- ';
                readme.push(value + line.trim());
            });
        }
    }
}
console.log(readme.join('\n'));