hm-doc only runs on ./src

[joelnet]

I am attempting to document this project https://github.com/joelnet/MojiScript. The code is not in an src directory.

I have created isArray.js inside of the function directory with the contents:

/* Determine if an array is empty.
    isEmpty([]) === true
*/
// isEmpty :: Array a -> Bool
const isEmpty = array =>
    Array.isArray(array)
    && array.length === 0

I then run the command npx hm-doc --files ./function/**/*.js and nothing is returned.

If I copy that file into src/isArray.js and run the command npx hm-doc --files ./function/**/*.js it works just fine.

It seems to only run on files in the src directory.

[joelnet]

I also need the ability to exclude files, like the examples directory. I don't want that in the documentation.

[JesterXL]

Interesting ok, lemme take a look tomorrow. I noticed glob and the other glob alternative have support for all kinds of features like excluding for example. I should probably just open up that functionality in case you need super control of your files. Thanks a lot for the detailed issue!

[joelnet]

Here's some debug info. I ran with the command DEBUG=hm-doc npx hm-doc --files ./type/**/*.js

  hm-doc parse, fileGlob: ./type/__tests__/is.test.js +0ms
  hm-doc loadFilenames, stringGlob: ./type/__tests__/is.test.js +8ms
  hm-doc loadFilenames result, err: null, files: [ './type/__tests__/is.test.js' ] +14ms
  hm-doc parse, files loaded, about to read them: [ './type/__tests__/is.test.js' ] +9ms
  hm-doc readFile, filename: './type/__tests__/is.test.js' +1ms
  hm-doc parse, fileContents loaded, attempting to parse out comments from AST... +4ms
  hm-doc codeToMarkdown start... +1ms
  hm-doc codeToMarkdown, parsing code... +1ms
  hm-doc parseCode, code: const is = require(' ... +0ms
  hm-doc parseCode, successfully parsed via babylon. +115ms
  hm-doc codeToMarkdown, getProgramBody... +1ms
  hm-doc codeToMarkdown, getComments... +3ms
  hm-doc codeToMarkdown, getCleanedComments... +1ms
  hm-doc codeToMarkdown, toTypeAndDocumentationPair... +0ms
  hm-doc codeToMarkdown, stripAST... +0ms
  hm-doc codeToMarkdown, trimmedStars... +1ms
  hm-doc codeToMarkdown, trimmedWhitespace... +0ms
  hm-doc codeToMarkdown, parsedComments... +0ms
  hm-doc codeToMarkdown, removeFailedCommentParsing... +1ms
  hm-doc codeToMarkdown, typeSignaturesAttached... +0ms
  hm-doc codeToMarkdown, filterFailedParsing... +0ms
  hm-doc codeToMarkdown, filterFailedParsing... +0ms
  hm-doc codeToMarkdown, filterLegitParsedComments done [] +1ms
  hm-doc codeToMarkdown, done. +0ms
  hm-doc parse, markdowns parsed, combining with file names: [ [] ] +0ms
  hm-doc loadFilenames, stringGlob: ./type/__tests__/is.test.js +1ms
  hm-doc loadFilenames result, err: null, files: [ './type/__tests__/is.test.js' ] +2ms
  hm-doc parse, combining filenames and markdown... +0ms
  hm-doc parse, cleaning empty results... +1ms
  hm-doc cleanEmptyResults, start: { './type/__tests__/is.test.js': [] } +1ms
  hm-doc cleanEmptyResults, end: {} +1ms
  hm-doc parse done, showing result {} +0ms
  hm-doc parse, done. +0ms
{}

My guess is that it's failing to parse the first file and then quits.

[JesterXL]

:: high five :: Cool, makes sense. Hoping the new glob has more verbose errors so I can bubble those up.

[JesterXL]

Ok @joelnet

1. for your first issue, try surrounding your glob with quotes. I downloaded your project, and it works if I change this: npx hm-doc --files ./function/**/*.js to this: npx hm-doc --files './function/**/*.js'
2. For exclusion of files, I've refactored it to accept glob options. On command-line, you can simply add --ignore 'some/*/glob' and it'll pass those to the glob ignore option: https://github.com/isaacs/node-glob#options

v1.2.0 from PR 2. Lemme know if this works and I'll close the issue.

[joelnet]

Very odd. the quotes seems to have fixed that problem.

I did notice that when I run it with a template i get different results. Only 1 function is included when I add a template.

$ npx hm-doc -f './list/*.js'
{ './list/filter.js':
   [ { hm: 'filter :: Function -> Filterable -> Array',
       description: undefined,
       hmParsed: [Object],
       signature: 'Function -> Filterable -> Array' } ],
  './list/head.js':
   [ { hm: 'head :: Array -> Any',
       description: undefined,
       hmParsed: [Object],
       signature: 'Array -> Any' } ],
  './list/join.js':
   [ { hm: 'join :: Array -> Array -> Array',
       description: undefined,
       hmParsed: [Object],
       signature: 'Array -> Array -> Array' } ],
  './list/map.js':
   [ { hm: 'map :: Function -> Mapable -> Array',
       description: undefined,
       hmParsed: [Object],
       signature: 'Function -> Mapable -> Array' } ],
  './list/range.js':
   [ { hm: 'range :: Number -> Number -> Iterable',
       description: undefined,
       hmParsed: [Object],
       signature: 'Number -> Number -> Iterable' } ],
  './list/reduce.js':
   [ { hm: 'reduce :: Function -> Any -> Iterable -> Any',
       description: undefined,
       hmParsed: [Object],
       signature: 'Function -> Any -> Iterable -> Any' } ],
  './list/reduceWhile.js':
   [ { hm:
        'reduceWhile :: Function -> Function -> Any -> Iterable -> Any',
       description: undefined,
       hmParsed: [Object],
       signature: 'Function -> Function -> Any -> Iterable -> Any' } ],
  './list/sort.js':
   [ { hm: 'sort :: Function -> Iterable -> Array',
       description: undefined,
       hmParsed: [Object],
       signature: 'Function -> Iterable -> Array' } ],
  './list/tail.js':
   [ { hm: 'tail :: Array -> Array',
       description: undefined,
       hmParsed: [Object],
       signature: 'Array -> Array' } ] }

vs

$ npx hm-doc -f './list/*.js' -t template.hbs
### Our Library

Sup! This is our library documentation. Install it like `npm i something --save`, and you're ready to do things.

### API

Below are all the functions we support in the public API.

## ./list/tail.js


## .tail
`Array -> Array`

### Support

Email us, we're here to help!

Also when I run it on the whole directory, I get a different error.

$ npx hm-doc -f '**/*.js' --ignore "node_modules"
{ [Error: EISDIR: illegal operation on a directory, read] errno: -21, code: 'EISDIR', syscall: 'read' }

[JesterXL]

Roger that, lemme hit some work stuff, then I'll check this week. Thanks a lot for the details, this is helpful.