Experienced Devs

3979 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:

Logo base by Delapouite under CC BY 3.0 with modifications to add a gradient

founded 1 year ago

MODERATORS

snowe

jmk1ng

drewsiferr

Is there a "markup language" to describe a debugging session? (sh.itjust.works)

submitted 6 months ago by [email protected] to c/experienced_devs

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

[–] [email protected] 2 points 6 months ago

I am a fan of structurizer and the C4 model in general.

I would use a single .dsl file and add the relationships and entities as you discover them. You can apply tags , and then write filtered views to only show specific tags for sub systems or workflows that a user will follow.

you can pair this with markdown/text notes that reference the png files of the views that structurizer will output.