jdi index.js) and it generates corresponding
.md files from your comments (e.g
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. — Donald E. Knuth, Literate Programming
Let's face it: The majority of JSDoc comments are completely useless and a waste of time for the author, as well as the reader.
We shouldn't (just) document what a particular piece of code does, instead we should focus on why it does what it does. Reading source code should be more like reading a guide, as opposed to reading a manual.
I think literate programming is a wonderful concept, but I don't think introducing a separate format for programs written in "literate" form is the right way to go. Instead we should continue extracting documentation from source code, but the comments should build "frame" around your code.
npm i jdi -g
jdi globally, so it can be used from the command line. Alternatively you can install
jdi locally as a
npm i jdi --save-dev
jdi is trivial. Just some source files to it and it will happily create corresponding Markdown documents:
~/r/jdi (master) $ jdi --help Usage: jdi [options] Options: -h, --help output usage information -V, --version output the version number
jdi supports globbing. If you want glob to perform the expansion on a system where the shell already does that (e.g. when using
fish shell), quote the file arguments:
Protip: Use a
Makefile for keeping your
.md files in-sync with your source files:
%.md: % @./node_modules/.bin/jdi $<
~/r/jdi (master) $ make index.js.md wrote 6385 bytes to index.js.md
But after the initial run, no further
.md files will be built:
~/r/jdi (master) $ make index.js.md make: `index.js.md' is up to date.
You can also
require('jdi') and use the public API directly.
Prior works of art
- Docco is quite similar, but instead of generating Markdown files, it generates HTML. Since everyone has their favorite Markdown editor anyways, I don't see any reason to actually render to generated Markdown to HTML (even though that would be trivial).
- literate-programming is deprecated. It also extracts code from your Markdown documents as opposed to extracting Markdown from your source code. While this is closer to the original idea behind literate programming, I don't think introducing an additional build step is the way to go.