this post was submitted on 17 May 2024
12 points (92.9% liked)

Experienced Devs

3978 readers
1 users here now

A community for discussion amongst professional software developers.

Posts should be relevant to those well into their careers.

For those looking to break into the industry, are hustling for their first job, or have just started their career and are looking for advice, check out:

founded 1 year ago
MODERATORS
snowe@programming.dev
jmk1ng@programming.dev
drewsiferr@programming.dev
12
Is there a "markup language" to describe a debugging session? (sh.itjust.works)
submitted 6 months ago by best_username_ever@sh.itjust.works to c/experienced_devs@programming.dev
10 comments fedilink hide all child comments
 

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!

you are viewing a single comment's thread
view the rest of the comments
[–] madnificent@lemmy.world 3 points 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).