I want to document my debugging sessions in a text file but I don’t know if anyone did this before.

I came up with this kind of “language” that is a mix between Markdown and C++, but I still wonder if something equivalent exists already.

// When you click on the button
# [click button]
- A::f()
// - ... other method calls, don't document if you don't need to

# A::f()
// "..." for "parameters" where you don't need the details
- Stuff::g(...)
- Stuff::h(...)

// <Class> is a fake template thing to show the possible types of an object
# <SubStuffA | SubStuffB> Stuff::g(...)
- Stuff::g() {} // empty but I use v/=> for virtual call
  v/=> SubStuffA::g()
  v/=> SubStuffB::g()

# SubStuffA::g()

# SubStuffB::g()

# Stuff::h(...)

I document methods in the order of appearance in the code.

If you have any good idea about a reliable way to document a list of function calls, I’m interested!

  • madnificent@lemmy.world
    3·
    6 months ago

    I write my notes in org-mode. It’s supported in many editors in a basic form, letting you add code snippets etc in an unobtrusive way. Using a well thought out format helps you in the long run.

    I use this in Emacs, through which it lets me refer to emails, execute code snippets, attach related files, fetch content on/from remote servers, send off the debug session as an html email, … Support will depend on your editor but even as raw text it works.

    I don’t use something specific to make non-code repeatable as you suggest here, but you could embed a test language in an org code block.

    The syntax is straight-forward and exports to multiple external formats exist (eg: html).