Use file-globs for sources

Hi! First of all, I would like to thank you for this project - superawesome generator, the only one of its kind!

As for the issue - currently I’m trying to set up documentation generation for my project and I’m running into some troubles with include/exclude params in config. First problem is that I cannot put my sources in one directory like it’s suggested in manual (src), because of legacy support. All sources are in root directory. Ok, I can handle this by filling exclude array in config with node_modules etc. Next problem is that the project is component-based and a single component directory contains lots of auxiliary js and jsx files, demo-pages, demo-scripts, etc. These files should not be documented, so I need to carefully set up includes array in config with heavy regexps just to filter out what I don’t need in documentation.

So, my suggestion is to deprecate sources, includes and excludes and to use file-globs like it’s done in gulp.src. It can be done either by specifying files as an array of glob-strings or by using array of plain file-paths.

Using globs in config:

module.exports = {
  files: ['./util/**/*.js', './components/**/*.jsx', '!./components/**/*.test.jsx']
}

Using file paths as a result of https://github.com/isaacs/node-glob package:

var glob = require('glob');
module.exports = {
  files: glob.sync(['./util/**/*.js', './components/**/*.jsx'], {
    ignore: ['./components/**/*.test.jsx']
  })
}

I think the second variant is more appropriate as it does not force you to use globs in library source and add an extra dependency - it’s for the end-user.

What do you think? I could create a pull-request after approval of this suggestment.

[h13i32maru]

@raveclassic Thanks for explanation!

What do you think the following changing?

• currently
  • config.source accepts directory path(string)
• changing
  • config.source accepts directory path(string) and file/directory paths(string array)

So, ESDoc will support the following both case.

// case1: specify directory path
{
  source: "path/to/directory"
}

// case2: specify file/directory paths
{
  source: ["path/to/directory", "path/to/file.js",,,]
}

[typhonrt]

I have created a comprehensive solution for multiple source path support with backward compatibility and an overview is available in #310.