Is require-following a good idea?

[tmcw]

cc @anandthakker @jfirebaugh @beaugunderson

Been thinking over #340 #132 and #140 and have been thinking: is require-following useful? One of the main things that led me to work on documentation in the first place is the usage of module-deps to find all included source code and document it. But is this actually a useful approach? I think we're seeing some downsides:

• Mixing shallow & dependency modes is difficult technically and conceptually
• require() statements don't always point to JavaScript files
• module-deps requires each file to be parsed twice
• using module-deps means that we have to run babelify in one place and babel in another, and manage the relationship between those two, making sure they can parse the same kinds of things.

This is all making me reconsider whether we don't want to support a simple non-require-following recursive-find-the-files API. Thoughts?

[jfirebaugh]

It's been a valuable feature for documenting mapbox-gl-js, and the points you list sound like the kinds of difficult implementation details that I'm appreciative of one project solving so lots of people don't have to reinvent.

[beaugunderson]

I'm in favor of simplifying if we don't lose too much. In the mapbox-gl-js case what would need to change? Would specifying ./js/**/*.js as the input to documentation not be enough?

[anandthakker]

Hmm, yeah -- it's true that I've sorta instinctively liked the module-deps thing, but now that you raise the question, I agree that it's not clear how much we're really getting from it. At first, I was gonna say that having awareness of the dependency graph (instead of just a flat list of files) might be useful for inference-related stuff; but then I think that anything we use to do such stuff would already need to have its own way of statically analyzing a codebase (e.g. flow). So yeah -- I'm 👍 for simplifying to files

[tmcw]

Okay: I think fork the time being let's stick with following module deps. There's some benefit, not a mind-blowing amount, but the cost of refactoring it away is likely more than the benefit of removing it right now.

[michaelBenin]

Would be nice this supported both resolving from an entry as well as specifying a directory.

I would like the flexibility of providing a glob over using an entry. Especially as some of my projects have multiple entry points.

[tmcw]

For the time being, --polyglot will turn off require-following and let you specify your documented files manually.

[balupton]

For the time being, --polyglot will turn off require-following and let you specify your documented files manually.

@tmcw do you mean --shallow?

[tmcw]

Er yeah, sorry - --shallow

[slashwhatever]

As a new documentation user, I'm having trouble getting a simple, recursive scan to work:

documentation --polyglot --shallow ~/xdev/bucket/platform/coreapp/platform/src/javascript/console/* -o ~/xdev/bucket/platform/coreapp/platform/doc/ -f html

I think that should run a recursive, simple scan of everything in the ..../console directory and pump it out to the .../doc directory in html.

But I get this: http://puu.sh/p5C5Q/264a66ac73.png

Bug or user error? (I think I know which :D )

[tmcw]

Hi @jangla!

Two things about that example -

Since the shell command you're calling doesn't include build or another command in it, it's likely that you're using documentation 3.x, which is a bit outdated. Try updating documentation.js for better results.

~/xdev/bucket/platform/coreapp/platform/src/javascript/console/*

This will list files and directories in console, but won't list them recursively - you can test this out by running

ls ~/xdev/bucket/platform/coreapp/platform/src/javascript/console/*

If you'd like to use shallow recursively, you can use a recursive glob, like

documentation build --polyglot --shallow ~/xdev/bucket/platform/coreapp/platform/src/javascript/console/**/.js -o ~/xdev/bucket/platform/coreapp/platform/doc/ -f html
``

[slashwhatever]

Hi @tmcw

That doesn't work, I assume because:

~/xdev/bucket/platform/coreapp/platform/src/javascript/console/**/.js

isn't correct.

Calling:

ls ~/xdev/bucket/platform/coreapp/platform/src/javascript/console/**/.js

Yields nothing: http://puu.sh/p6HtO/b08b11f594.png

Calling:

ls ~/xdev/bucket/platform/coreapp/platform/src/javascript/console/**/*.js

does list all the js files. However, placing that in the call to documentationjs just yields this: http://puu.sh/p6HCb/a4c7292298.png

I'm using documentation v3.0.4

P.S. Sorry for the thread hijack - just trying to get this to work as it seems a better fit for us than straight JSDoc :)