Suggestion: Print docstring for instructions executed in trace as part of report

[Vaguery]

I often find myself explaining, step by step, what a trace is doing in each step. The constants and input values are straightforward; the instructions can be more complicated.

I'd like to suggest printing the docstring for each instruction as it's executed in a trace, for the reader. Needless to say, if there's some other use (besides being read by a human being) for the trace itself, this could be an option. But it seems like it would be almost universally helpful for any trace, especially for people unfamiliar with the details of complex instructions, like 'exec_do*range.

[Shalmezad]

Still learning clojure, but would something like this work for what you need?

[Vaguery]

Yes, though I'm not sure how those would work for some of the indirectly-constructed instruction functions, like integer_add, which is built form an adder in the Clojush code.

But I was just thinking of adding a line to the report in each step like this (untested) code

(defn trace-event-string
  "Describes an item being processed in this step, or gives its docstring if it's an instruction"
  [item]
  (let [push-type (util/recognize-literal item)]
    (cond
      push-type
        (str item " is a " push-type " literal")
      (and (symbol? item) 
           (re-seq #"in\d+" (name item)))
        (str item " is an input instruction")
      (contains? @instruction-table item)
        (str item "instruction: " (:doc (meta (var item))))
      :else
        (str item)
      )))

[Shalmezad]

It looks like integer_add still uses defined_registered:

(define-registered integer_add (with-meta (adder :integer) {:stack-types [:integer]}))

Meaning it could still be documented the same way:

(define-registered integer_add (with-meta (adder :integer) {:stack-types [:integer]})
  "Pushes the sum of the top two items.")

Definitely agree on moving it from within eval-push to it's own function though (and handling non-instructions as well), will take another stab at it this weekend.