Why must --files be used when I'm using conf.json?

[justin-calleja]

I'm passing -c conf.json to jsdoc2md:

jsdoc2md --template readmeTpl.hbs --no-cache -c doc/conf.json --files lib/* >> README.md

I'd like to include lib/* in doc/conf.json's source.include below:

  "source": {
    "include": [
      "node_modules/@justinc/jsdocs/typedefs/index.jsdoc",
      "node_modules/@justinc/jsdocs/typedefs/Tuple.jsdoc"
    ]
  }

but I can't do that as jsdoc errors out without --files.

[75lb]

how about you deleted the include property of jsdoc conf and passed all input files to jsdoc2md? You can store this command as an npm script..

jsdoc2md --template readmeTpl.hbs --no-cache -c doc/conf.json --files lib/* node_modules/@justinc/jsdocs/typedefs/*.jsdoc >> README.md

[justin-calleja]

I started out that way, but it gets a bit long to include in an npm script.

Note that I cannot glob like so: node_modules/@justinc/jsdocs/typedefs/*.jsdoc as there are files I want jsdoc2md to not include (the idea with node_modules/@justinc/jsdocs/ is to "pick and choose" the "common" JSDoc documentation relevant to a given project).

[75lb]

I started out that way, but it gets a bit long to include in an npm script.

Then do it a different way - there are plenty of options.

Note that I cannot glob like so: node_modules/@justinc/jsdocs/typedefs/*.jsdoc as there are files I want jsdoc2md to not include

Ok, if the * wildcard doesn't suit you then use a different one.

[justin-calleja]

I was not using * I was using node_modules/@justinc/jsdocs/typedefs/{index,Tuple}.hbs which is workable for this use case but it doesn't scale if there are other files to include from other modules.

I brought this issue up because I thought jsdoc2md can be made better if the user is not required to supply --files / --source when they're using a jsdoc config file. CLI opts can be used to overwrite config in the file but why force me to have my config in 2 places.

In any case - it's not a blocker, just a suggestion. ... of course there are ways around it

[75lb]

internally, the values from jsdoc2md's --files option are passed directly to the jsdoc command..

So, when you run jsdoc2md using the options in your first comment, internally jsdoc will be executed something like this:

jsdoc -X --configure doc/conf.json lib/*

This command yields the JSON that jsdoc2md shapes (via jsdoc-parse) into useful input for jsdoc2md's output template (dmd).

So, it's up to us (the user) whether we supply the files directly to the jsdoc command (via --files) or via the jsdoc config file (via -c or --configure).

I would accept a PR for the improvement you suggest (to make --files optional in the case input files are detected in the jsdoc config file) but it's not high priority at the moment. Leaving open in case someone to wants to pick this up.

[justin-calleja]

Ok, understood. I thought it was simply a matter of turning off required flags via some option in jsdoc2md's config.

:beer:

[deobald]

It would be wonderful if jsdoc2md had this symmetry with jsdoc. Seven years later, I'm happy to add a small +1 to this, but I realize it may still not be a priority.