forked from google/clasp
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add doc generator. Add missing JSDoc comments
- Loading branch information
Showing
5 changed files
with
1,241 additions
and
403 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| /** | ||
| * 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. | ||
| */ | ||
| const fs = require('fs'); | ||
| const parseComments = require('parse-comments'); | ||
| const extract = require('extract-comments'); | ||
| const file = fs.readFileSync('./index.ts').toString(); | ||
| const ucfirst = require('ucfirst'); | ||
|
|
||
| // The README will be a concatenation of lines in this variable. | ||
| let readme = [ | ||
| '## How To...', | ||
| ]; | ||
|
|
||
| // Remove first line (#!/usr/bin/env node) | ||
| const fileLines = file.split('\n'); | ||
| fileLines.splice(0, 1); | ||
| const fileWithoutFirstLine = fileLines.join('\n'); | ||
|
|
||
| // Extract JSDoc comments out of our file. | ||
| const comments = extract(fileWithoutFirstLine); | ||
| for (const command of comments) { | ||
| // To use the parseComments module, complete the stripped comment. | ||
| const comment = `/*${command.raw}*/`; | ||
| const 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(param => { | ||
| const isOptional = param.type.indexOf('?') !== -1; | ||
| // readme.push(JSON.stringify(param)); | ||
| const 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'); | ||
| const examples = claspCommand.example.split(','); | ||
| examples.map(example => { | ||
| readme.push(`- \`clasp ${example}\``); | ||
| }); | ||
| } | ||
| // Extra Description (@desc) | ||
| if (claspCommand.desc) { | ||
| readme.push(''); | ||
| const lines = claspCommand.desc.split('-'); | ||
| lines.map((line, i) => { | ||
| let value = ''; | ||
| if (i) value += '- '; | ||
| readme.push(value + line.trim()); | ||
| }); | ||
| } | ||
| } | ||
| } | ||
| console.log(readme.join('\n')); |
Oops, something went wrong.