Runtime documentation access

[tmcw]

USE CASE: You've built a REPL or another type of JavaScript editor, and you're importing different JavaScript libraries and want to show documentation for their methods, dynamically. Right now, you could use a documentation generator, figure out what you've referenced, parse and analyze the code for documentation, and match it up. But that means re-parsing an entire source tree, even though you have the objects at hand.

So: what about runtime accessibility of documentation information?

For example: Python's docstrings become a .__doc__ property, which is accessible by repls. Clojure's documentation is stored in meta information. These languages allow runtime referencing of documentation.

One possibility for JavaScript (hattip @mbostock) would be to place documentation inside of functions, instead of right before then, such that the documentation would be accessible when you run function.toString(), like:

function add(a, b) {
   // Add two numbers
   return a + b;
}

[tmcw]

Another possibility: decorators:

@doc(`Add two numbers`);
function add(a, b) {
   return a + b;
}

Which would add to a... global WeakMap of documentation like

new WeakMap([[add, { description: 'add two numbers']]);

[jamiebuilds]

Would a Babel plugin be an acceptable way to do this?

[tmcw]

I think a babel plugin could do even better and attach comment-based documentation to exports, right? It could essentially compile

// divide two numbers
export function divide(a, b) {
   return a / b;
}

to

import { documentation } from "runtime-documentation";
export function divide(a, b) {
   return a / b;
}

documentation.add(divide, 'divide two numbers');

and then you could run

$ node -r @std/esm -r runtime-documentation
> import { divide } from "./divide.js";
> doc(divide);

> 'divide two numbers'

I think? Not sure if this is the right route here, but some approach to runtime documentation is more and more of interest to me (admittedly because of the @observablehq usecase being front & center)

[jamiebuilds]

Yeah, you could do that fairly easily.

But I'm interested in what the use case for Observable is