
Margin Notes: Automatic code documentation with recorded examples from runtime - mpweiher
https://geoffreylitt.com/margin-notes/
======
weaksauce
This is really neat. It would be awesome if something like this was added into
the language server protocol so you could have it everywhere and standardized.

~~~
gklitt
Yeah, the examples are serialized so it's theoretically possible example
recorders in any language that emit a standard format. It's kind of just a
logging format in some sense.

On the viewer side I've thought about building a Sourcegraph extension which
would consume a standardized trace format and then display it in any editor,
on Github, etc.

------
chewxy
Slightly related are Go examples - they're tests, and documentation at the
same time. It'd be nice if someone hooks in a listener to automatically
collect examples tho

~~~
pmontra
And Elixir's doctests [https://elixir-lang.org/getting-started/mix-otp/docs-
tests-a...](https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-
with.html)

~~~
merlincorey
And Python's Axe!

I mean doctest:
[https://docs.python.org/3/library/doctest.html](https://docs.python.org/3/library/doctest.html)

~~~
westurner
1\. sys.settrace() for {call, return, exception, c_call, c_return, and
c_exception}

2\. Serialize as/to doctests. Is there a good way to serialize Python objects
as Python code?

3\. Add doctests to callables' docstrings with AST

Mutation testing tools may have already implemented serialization to doctests
but IDK about docstring modification.

... MOSES is an evolutionary algorithm that mutates and simplifies a combo
tree until it has built a function with less error for the given input/output
pairs.

------
wtroughton
I'm surprised that there isn't more adoption of tools like this to help
developers understand code.

Even for statically typed languages like Java, I find the existing tools
lacking in helping me understand the code thoroughly. I mostly rely on the IDE
to navigate code which I then mentally jot down the behavior of the code
segment. Writing code this way is way too error-prone, and unfortunately
testing isn't foolproof either.

It isn't until something breaks that we really begin to learn the nuances of
the system...

------
jmiserez
Very cool. One could do this over time, and then automatically find out where
values change between different versions of the code. Might be able to find
bugs before they ever occur.

------
drudru11
Nicely done - excellent presentation. I hope this becomes a thing in Visual
Studio Code.

