SCRYDOSBox-XReferenceCommentscomment_writeAlso in MAME

DOSBox-XComments

comment_write

Change the saved comments: add or delete one, or save them all to a file and load them back.

comment_write(method, ref="", text="", dest="", path="")

Try it

On Bricks, the game this repository builds, stopped on its play screen with bricks.sym loaded, which names the routine brick_hit.
Ask

Leave a note on the routine that removes a brick: AL is the row, BL the column.

Call
comment_write(method="add", ref="brick_hit", text="AL = row, BL = column of the brick that falls")
Reply 3 of 5 fields
{
  "summary": "comment_write add: brick_hit at 0x000090b8, stored",
  "status": "ok",
  "replaced_comments": []
}

The comment is saved on brick_hit, which is the linear address 0x90b8. Nothing was there before, so replaced_comments is empty.

The whole reply
JSON
{
  "summary": "comment_write add: brick_hit at 0x000090b8, stored",
  "status": "ok",
  "comment": {
    "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"
  },
  "replaced_comments": [],
  "declarations": {"persistent": true, "path": "<volatile>"}
}

The four methods

method what it does
add Puts text on ref. A comment already there is replaced.
delete Removes the comment at ref.
save Writes every comment to the file dest.
load Reads the comment file at path into the saved comments, all or nothing.

Arguments

method one of "add", "delete", "save", "load", required
add, delete, save or load, as above.
ref string, default ""
For add and delete: a symbol or a SEG:OFF.
text string, default ""
For add: one printable line, at most 237 UTF-8 bytes.
dest string, default ""
For save: the file to write, an absolute or ~-led path. A comment file already there is replaced; any other file is refused.
path string, default ""
For load: the comment file to read, an absolute path.

What comes back

comment
add: the comment as saved, a row as comment_list gives it.
replaced_comments
add and load: the comments whose text was replaced, as they were.
deleted
delete: the comment removed.
dropped_comments
save: comments only the replaced file held, each by ref. They are gone from the file.
added
load: how many comments are new. unchanged counts those already saved with the same text, parsed the rows read.
All 13 reply fields
  • added (integer)
  • comment (object)
  • comments_total (integer)
  • declarations (object)
  • deleted (object)
  • dropped_comments (array)
  • dropped_total (integer)
  • parsed (integer)
  • path (string)
  • replaced_comments (array)
  • replaced_total (integer)
  • truncated (boolean)
  • unchanged (integer)

What it refuses

Why it works this way

One address shows one comment, however it is spelled: start, 0824:000B and 0814:010B can name one byte. An add where a comment exists replaces its text.

save and load are how a project keeps its comments under version control beside its symbol file. load is all or nothing, and the file wins where both comment an address.

More on why
  • A comment sets nothing in the debugger, so it never stops the program.
  • A symbol the loaded symbol table lacks is saved unresolved, and resolves once a table has it.
  • A raw SEG:OFF comment is stale while the build it was written over is not the one loaded, as a raw breakpoint is.
  • Comments a rebuild or a load brought to one address are all kept. A call reaches the one whose ref it spells.
  • The file's cpu column is written empty, since a DOS machine has one processor. A file that fills it is refused.
  • The file has no build column: a raw address is trusted for the build it is loaded into.
  • A file saved before symbols_load, or while the program runs, can hold two rows that a later stop resolves to one byte.
  • A load keeps both such rows and names them in note. A save refuses them until one is deleted.
  • A load that gives a stale raw comment the text it already holds adopts it into this session and build.
  • A row a load cannot resolve at this stop is kept unarmable, its why naming the stop it waits for. An add refuses such an address.
  • comments_total, dropped_total and replaced_total count the whole lists; truncated says a list was cut. declarations names the saved breakpoints file, as in comment_list.
The contract your client receives
Text
Change this conf's comments.

`add`: `text` (one printable line, at most 237 UTF-8 bytes) on `ref`,
a symbol or a `SEG:OFF`; a second there replaces it. Reply: `comment`, `replaced_comments`,
`declarations`, `note`.

`delete`: the comment `ref` names. Reply: `deleted`, `declarations`, `note`.

`save`: every comment to `dest`, an absolute or `~`-led path, replacing a comment file
there (rows only it held in `dropped_comments`); any other file is refused; answers on a
running machine. Reply: `path`, `comments_total`, `dropped_comments`, `dropped_total`,
`truncated`, `note`.

`load`: the comment file at `path`, all or nothing, the file winning. Reply: `path`,
`parsed`, `added`, `replaced_comments`, `replaced_total`, `truncated`, `unchanged`,
`comments_total`, `declarations`, `note`.

`add`, `delete` and `load` need the machine stopped. Refused: an argument the method
does not take, a misshapen `ref` or `text`, a `save` `dest` that is the declaration store's
file, compared without regard to case on any volume (`bad_argument`), a name defined twice
(`ambiguous_ref`), an unknown `ref` (`unknown_ref`), an unwritable store (`host_failed`).

Reference: REFERENCE.md, Breakpoints and watches.
Tools