Margin Notes: Automatic code documentation with recorded examples from runtime | Hacker News Reader

Margin Notes: Automatic code documentation with recorded examples from runtime

geoffreylitt.com

81 pointsmpweiher10 comments

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.

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.

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

And Elixir's doctests https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...

And Python's Axe!

I mean doctest: https://docs.python.org/3/library/doctest.html

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.

Yeah, I like doctests but also find it limiting to have everything in the source code text. Having a GUI for viewing examples is nice, although it does introduce other problems like how to store and version the examples.

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...

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.

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

Reply on news.ycombinator.com