Generate README Doc

[grant]

Expected Behavior

The README methods should be generated from the TypeScript file.

Actual Behavior

The README is slightly out of date, duplicates jsdoc comments, and must be hand edited.

Solution

• Create a file called generateDocs.ts.
• Running tsc generateDocs.ts && node generateDocs.js should build the README without modifications needed.
  • This script should use the TS Compiler API over index.ts. A header and footer would be added to the README.
• A test should check that the current README file matches the latest generated README file.

[grant]

This npm module (esprima) looks promising.

Example:

var esprima = require('esprima');
var program = `
const answer = 42
console.log('hi');

commander
  .command('create [scriptTitle] [scriptParentId]')
  .description('Create a script')
  .action(create);

/**
 * Fetches a project and saves the script id locally.
 */
commander
  .command('clone [scriptId] [versionNumber]')
  .description('Clone a project')
  .action(clone);
`;

var p = esprima.parse(program);
console.log(JSON.stringify(p, null, 2));

But it does not parse comments.

[campionfellin]

jsdoc might be nice, since we write our comments using their format already. Looks like there is jsdoc2md to generate the ReadMe.

[grant]

The problem is most tools assume js, not ts.
For jsdoc2md, the parser only detects functions and not the commander.command syntax (it is blank).

[grant]

OK, so I think we can generate a README if we just parse the ts comments in one file.
We can use this library that doesn't care about the actual filetype or syntax, it just looks at the comments and provides a nice AST:

https://github.com/jonschlinkert/parse-comments

Example:

const str = `
/**
 * Read in source files from file paths or glob patterns. 
 *
 * js
 * verb.src('src/*.hbs', {layout: 'default'});
 * 
 *
 * **Example usage**
 *
 * js
 * verb.task('site', function() {
 *   verb.src('src/*.hbs', {layout: 'default'})
 *     verb.dest('dist');
 * });
 * 
 *
 * @param {String|Array} \`glob\` Glob patterns or file paths to source files.
 * @param {Object} \`options\` Options or locals to merge into the context and/or pass to \`src\` plugins
 * @api public
 */
function foo() {
  
}
/**
 * Bat bat
 */
`;
var comments = require('parse-comments');
var s = comments(str);
console.log(s);