SCRYDOSBox-XReferenceCommentscomment_listAlso in MAME

DOSBox-XComments

comment_list

List every saved comment of this program, each with its address and whether it resolves now.

comment_list()

Try it

On Bricks, the game this repository builds, stopped on its play screen, right after the comment of the entry below was added.
Ask

Which comments are saved for this game?

Call
comment_list()
Reply 4 of 6 fields
{
  "summary": "comment_list: 1 comment",
  "status": "ok",
  "comments_total": 1,
  "truncated": false
}

One comment is saved, and truncated is false: the reply lists every one.

The whole reply
JSON
{
  "summary": "comment_list: 1 comment",
  "status": "ok",
  "comments": [
    {
      "ref": "brick_hit",
      "by": "symbol",
      "cpu": {"available": false, "why": "a DOS machine has one cpu, and every row acts on it"},
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "text": "AL = row, BL = column of the brick that falls",
      "addr": "0x000090b8",
      "state": "resolved"
    }
  ],
  "comments_total": 1,
  "truncated": false,
  "declarations": {"persistent": true, "path": "<volatile>"}
}

Arguments

Takes no argument.

What comes back

comments
The comments this reply shows. Each row has ref, text, addr once resolved, state, and why when it does not resolve.
comments_total
How many comments are saved, listed or not.
truncated
true when there are more comments than the reply lists. comment_write(method="save") writes them all.
declarations
The saved breakpoints file the comments live in: its path, and persistent, which is true for a file on disk.
All 4 reply fields
  • comments (array)
  • comments_total (integer)
  • declarations (object)
  • truncated (boolean)

Why it works this way

It reads the saved comments and types nothing at the debugger, so it answers while the program runs. Rows come in the order they were saved.

More on why

What state says of a comment:

  • resolved: its ref resolves to an address now.

  • unresolved: no such symbol in the loaded symbol table.

  • ambiguous: its name matches several symbols.

  • stale: a raw SEG:OFF not known to be this build's.

  • unarmable: its address cannot be worked out now, for instance a protected-mode SEG:OFF until a stop reads its selector's base.

  • Each row also carries by, cpu, created_at, origin, inherited and age_s, as a saved breakpoint's row does.

  • A row's cpu is always an object with available set to false and a why: a DOS machine has one cpu.

  • orphan: true is on a row saved with no record of its session.

  • While the program runs the reply adds last_stop.

The contract your client receives
Text
Every comment of this conf, in store order. Answers on a running guest too.

Reply: `comments` (each `ref`, `text`, `addr`, `state`, `why`),
`comments_total`, `truncated`, `declarations`.

Reference: REFERENCE.md, Breakpoints and watches.
Tools