archive-gh-me/documentation
1
0
Fork 0
mirror of https://github.com/documentationjs/documentation.git synced 2026-01-18 14:17:30 +00:00
Code Issues Projects Releases Wiki Activity
documentation/docs/POLYGLOT.md
Tom MacWright cb8fdfa74f feat(bin): Support globs on windows and use smarter recursion (#629) 
This brings logic from eslint over to documentation: instead of readdirSync, we're using the glob
module. This also, I hope, will let us support globs on Windows without changing OSX/Linux behavior.
Fixes #607
2016-12-26 10:24:30 -05:00

2.0 KiB
Raw Blame History

About documentation.js, polyglot mode, and file extensions

Base assumptions:

  • documentation.js subsists on a combination of source comments and smart inferences from source code.
  • The default mode of documentation.js is parsing JavaScript, but it has another mode, called --polyglot mode, that doesn't include any inference at all and lets you document other kinds of source code.
  • The default settings for everything should work for most projects, but this is a guide for if you have a particular setup.

File extensions

Let's talk about file extensions. We have two different flags for controlling file extensions: requireExtension and parseExtension.

  • requireExtension adds additional filetypes to the node.js require() method. By default, you can call, for instance, require('foo'), and the require algorithm will look for foo.js, foo the module, and foo.json. Adding another extension in requireExtension lets it look for foo.otherextension.
  • parseExtension adds additional filetypes to the list of filetypes documentation.js thinks it can parse, and it also adds those additional filetypes to the default files it looks for when you specify a directory or glob as input.

Polyglot

Polyglot mode switches documentation.js from running on babylon and babel as a JavaScript parser, to using get-comments. This lets it grab comments formatted in the /** Comment */ style from source code that isn't JavaScript, like C++ or CSS code.

Since documentation.js doesn't parse C++ and lots of other languages (parsing JavaScript is complicated enough!), it can't make any of its smart inferences about their source code: it just takes documentation comments and shows them as-is.

You can use polyglot mode to turn off inference across the board, but I don't recommend it. See the 'too much inference' topic in TROUBLESHOOTING.md for detail about that.