Optional function arguments / cell annotations

[kelleyvanevert]

I often find myself following the workflow of slowly transforming the cells with code that I’m working on, to helper functions, accumulating these ‘helper function cells’ as I go. Because I love the aspects of Observable that make it ‘accessible’ (for teaching, explaining, understanding code, etc), I also like to annotate these functions with their types (or, a high level human readable version of these) by using viewof and an auxiliary helper (like def(annotation, fn)) instead of having them just display as “f somefunc(…)” (which is already pretty, btw). (See image below.)

Optional function arguments
It is noteworthy that optional parameters to function disappear in the cell’s automatic display. (I.e. if a function takes optional parameters, the cell’s display changes from “f somefunc(a,b)” to “f somefunc(…)”). I think a small effort to show optional parameters would greatly improve the understandability of a notebook. (Being able to understand a cell at a glance, instead of having to open/close it.)

Cell annotations
This one’s just a wild idea. Focusing on the aim to encourage people to write their notebooks in such a way that they can be ‘read’ in an informative way (i.e. notebooks as a method of sharing knowledge and examples, as distinct from: notebooks as an iterative, feedback-oriented method of developing code) — I think it might be useful to provide notebook writers direct / easy means to give notebook readers an idea of what’s inside a collapsed cell. (Pinning a cell open isn’t always the best thing to do, too much code at once can be daunting to a reader.) My method of using viewof and an auxiliary def helper is possible, but maybe it would be encouraging to notebook writers to work this way if something would be built in for this particular case. For example, an annotate operator, that could be used like thus:

somefunc = function (a,b) {
  ...
}

annotate md`This is a function that ...`

…so that the collapsed cell would display as:

f somefunc(a,b)

This is a function that…

This would be a ‘open’ solution, leaving the possibilites open to the creativity of the community (who know, maybe people will start annotating their functions with cool interactive displays of what the function does, or …).

[tom]

Hi Kelley!

Cool, so:

• Optional function arguments: yep! We originally included them in our function formatting, because we were essentially stringifying functions and being very liberal about what we showed, but the current formatting is much more conservative - it parses argument names and bails out if we see a =. The rationale there is that optional function arguments can have anything as a value - even a gigantic JavaScript expression - and we still need to figure out where to draw the line - which kinds of function arguments should be shown in the short version. Perhaps we can just say, literals get printed, everything else collapsed?
• Annotations - we’d love something like python’s docstrings or clojure’s meta system to be a reality in JavaScript, and I’ve been tinkering with the idea. It’ll likely require a new spec and documentation ecosystem, but the payoffs - not only getting nice output in Observable but also getting inline documentation from 3rd party libraries - makes it something that we’re all pretty game to invest some time in.

-Tom