{"action":"created","issue":{"url":"https://api.github.com/repos/esdoc/esdoc/issues/310","repository_url":"https://api.github.com/repos/esdoc/esdoc","labels_url":"https://api.github.com/repos/esdoc/esdoc/issues/310/labels{/name}","comments_url":"https://api.github.com/repos/esdoc/esdoc/issues/310/comments","events_url":"https://api.github.com/repos/esdoc/esdoc/issues/310/events","html_url":"https://github.com/esdoc/esdoc/issues/310","id":167222904,"number":310,"title":"Multiple source paths solution / proof of concept fixes #72, #86, #210, #270","user":{"login":"typhonrt","id":311473,"avatar_url":"https://avatars.githubusercontent.com/u/311473?v=3","gravatar_id":"","url":"https://api.github.com/users/typhonrt","html_url":"https://github.com/typhonrt","followers_url":"https://api.github.com/users/typhonrt/followers","following_url":"https://api.github.com/users/typhonrt/following{/other_user}","gists_url":"https://api.github.com/users/typhonrt/gists{/gist_id}","starred_url":"https://api.github.com/users/typhonrt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/typhonrt/subscriptions","organizations_url":"https://api.github.com/users/typhonrt/orgs","repos_url":"https://api.github.com/users/typhonrt/repos","events_url":"https://api.github.com/users/typhonrt/events{/privacy}","received_events_url":"https://api.github.com/users/typhonrt/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":8,"created_at":"2016-07-24T08:14:39Z","updated_at":"2016-08-31T07:49:52Z","closed_at":null,"body":"There have been several issues opened #72, #86, #210, #270 regarding supporting multiple source (and test paths). @h13i32maru [currently in March has declined](https://github.com/esdoc/esdoc/issues/72#issuecomment-195889544) to support this feature with the claim it is too complex for ESDoc, but my proof of concept implementation hopefully proves that it works fine while maintaining backward compatibility. It took ~20 minutes to get the first implementation working then ~3 hours to make it \"bullet proof\". \r\n\r\nI have a test branch [source-globs](https://github.com/typhonjs-node-esdoc/esdoc/tree/source-globs) that seems to offer a great solution. Since I have done the proof of concept work in a branch of my fork of [ESDoc which supports Babylon](https://github.com/typhonjs-node-esdoc/esdoc) I'm posting a new issue here instead of a PR especially given that this is a potential major (but non-breaking) change. \r\n\r\nI'd like to open comments in support of adding this feature into ESDoc and of course get any feedback on the implementation. \r\n\r\nYou can install it via:\r\n`npm install \"git+https://git@github.com/typhonjs-node-esdoc/esdoc.git#source-globs\"`\r\n\r\nOr including the above in `package.json`. \r\n\r\n@h13i32maru I now have two major enhancements for ESDoc including the switch to Babylon parser and supporting multiple source / test globs which I'd like to upstream to ESDoc. Please consider accepting them! If you can agree to quickly review and accept PRs I'll certainly take the time to submit them! In my opinion after accepting these changes a new release `0.5` of ESDoc is pertinent. \r\n\r\n-------------\r\n\r\nThe following is a description of the changes involved in the proof of concept.\r\n\r\nI've included the `glob` npm module and treat `config.source` if it is an array then as an array of globs otherwise the string path is converted into an array with an all inclusive glob created from the string path as the single entry. Also if`config.test.source` is an array it also is treated as an array of globs, etc. \r\n\r\nSo if you were to include three source paths the following config file applies:\r\n```\r\n{\r\n   \"source\": [\"src/**/*.js\", \"src2/**/*.js\", \"src3/subdir/*.js\"],\r\n   \"destination\": \"docs\"\r\n}\r\n```\r\n\r\nIt should be noted that `config.source` / `config.test.source` now holds an array of globs as a bare string path is converted into a glob and stored as the single entry in an array. There are two new config parameters which store the base working path for source and tests which are `config.sourceDirPath` and `config.test.dirPath`.  To retain backward compatibility if either `config.source` or `config.test.source` is originally a path string then those paths define `config.sourceDirPath` and `config.test.dirPath`, but the user now has an option to override and provide in the config file `config.sourceDirPath` and `config.test.dirPath` which will be used in place instead of being generated. If not provided at all then they are set to the root path `.` when a source glob array is defined.\r\n\r\nAn example of including multiple paths relative to a user defined source directory path:\r\n```\r\n{\r\n   \"source\": [\"otherpath/src/subdir1/**/*.js\", \"otherpath/src/subdir2/**/*.js\", \"otherpath/src/subdir3/**/*.js\"],\r\n   \"sourceDirPath\": \"otherpath/src\",\r\n   \"destination\": \"docs\"\r\n}\r\n```\r\n\r\n-----\r\n\r\nI added a basic sanity check in tests to just make sure things work with source glob arrays. I have tested this in a few separate repos and so far things work great for source and test loading for existing ESDoc config files and supporting the new source globs array pattern.\r\n\r\nWhile two new config parameters are added (`config.sourceDirPath` and `config.test.dirPath`) they are not necessary to set in advance, so any existing ESDoc config file works as expected.  \r\n\r\n-----\r\n\r\n**Impacts**\r\n\r\nWith any major change it's important to consider the impact it might have on ESDoc plugins. As far as I'm aware I'm the only author of an ESDoc plugin, [esdoc-plugin-jspm](https://www.npmjs.com/package/esdoc-plugin-jspm) which uses the _old hack_ of rewriting / synthesizing the `config.includes` regexp to include multiple source directories supporting JSPM managed source code. I don't believe any other existing ESDoc plugins may be impacted and supporting source globs is a much preferred direction for `esdoc-plugin-jspm` because it prevents usage of `config.includes` by overwriting it.\r\n\r\nGiven that a bare source path is rewritten to a source glob array and stored in `config.source` and `config.test.source` and the new `config.sourceDirPath` and `config.test.dirPath` entries contain the actual paths there is a potential for ESDoc plugins to be updated. This affects my plugin [esdoc-plugin-enhanced-navigation](https://www.npmjs.com/package/esdoc-plugin-enhanced-navigation), but has low impact. In that plugin I used the old `config.source` to rewrite file paths for the navigation. This can actually now be _removed_.\r\n\r\nSo, there may be a minor impact on a few ESDoc plugins, but the feature enhancement is much improved and since ESDoc is no where near `v1.0` any affected plugins (if any at all outside my efforts) can easily make the change to use `config.sourceDirPath` as necessary."},"comment":{"url":"https://api.github.com/repos/esdoc/esdoc/issues/comments/243685981","html_url":"https://github.com/esdoc/esdoc/issues/310#issuecomment-243685981","issue_url":"https://api.github.com/repos/esdoc/esdoc/issues/310","id":243685981,"user":{"login":"raveclassic","id":1743568,"avatar_url":"https://avatars.githubusercontent.com/u/1743568?v=3","gravatar_id":"","url":"https://api.github.com/users/raveclassic","html_url":"https://github.com/raveclassic","followers_url":"https://api.github.com/users/raveclassic/followers","following_url":"https://api.github.com/users/raveclassic/following{/other_user}","gists_url":"https://api.github.com/users/raveclassic/gists{/gist_id}","starred_url":"https://api.github.com/users/raveclassic/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/raveclassic/subscriptions","organizations_url":"https://api.github.com/users/raveclassic/orgs","repos_url":"https://api.github.com/users/raveclassic/repos","events_url":"https://api.github.com/users/raveclassic/events{/privacy}","received_events_url":"https://api.github.com/users/raveclassic/received_events","type":"User","site_admin":false},"created_at":"2016-08-31T07:49:52Z","updated_at":"2016-08-31T07:49:52Z","body":"Guys, the solution ESDoc provides for documenting JS is really far from complete. \r\nWe've been trying to adopt our codebase for ESDoc struggling with unsupported features and missed edge cases but at last we've ended with `typedoc` and separate `.d.ts` files. We are also really lucky that WebStorm picks up `.d.ts` to help with code inspections.\r\n\r\nOur security policy does not allow to point to github (yep that's weird but that's it) so we need ESDoc to be published to npm. So, @typhonrt,  thank you for the effort you put to ESDoc with your fork. It's really promising and I do believe @h13i32maru will someday merge it.\r\n\r\nSumming up for now we're with typedoc but looking forward to further development of esdoc."}}
{"actor":{"display_login":"raveclassic"}}