Re:Margin Notes: Automatic code documentation with recorded ...
by weaksauce on Wednesday November 28, 2018 @03:56PM
(#18555600)
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.
Re:Margin Notes: Automatic code documentation with recorded ...
by gklitt on Wednesday November 28, 2018 @07:07PM
(#18556930)
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.
Re:Margin Notes: Automatic code documentation with recorded ...
by chewxy on Tuesday November 27, 2018 @11:24PM
(#18549276)
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
Re:Margin Notes: Automatic code documentation with recorded ...
by westurner on Thursday November 29, 2018 @06:03AM
(#18559384)
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.
Re:Margin Notes: Automatic code documentation with recorded ...
by gklitt on Wednesday November 28, 2018 @07:08PM
(#18556934)
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.
Re:Margin Notes: Automatic code documentation with recorded ...
by wtroughton on Wednesday November 28, 2018 @10:46PM
(#18557900)
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...
Re:Margin Notes: Automatic code documentation with recorded ...
by jmiserez on Wednesday November 28, 2018 @06:45PM
(#18556785)
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.
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.
I mean doctest: https://docs.python.org/3/library/doctest.html
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.
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...