asar icon indicating copy to clipboard operation
asar copied to clipboard

Add documentation about error/warnings IDs along with the error message

Open Atari2 opened this issue 3 years ago • 4 comments

This PR adds a small change to the docs to add 2 tables that have the association ID->name->small description for both errors and warnings. I found myself needing this more than once so I thought might as well add it.

The tables are auto-generated from asar's source code. They can be improved later (and they should), but this is a base stub that works and has all the information someone might need.

This could close #156 but that's up to the maintainers.

Atari2 avatar Dec 30 '21 11:12 Atari2

This could be useful. I think I recall someone asking for this, but I don't quite remember who or where.

I have a few suggestions:

  • If the lists are auto-generated, then whatever was used to generate the lists (I assume a script?) should also be commited. Otherwise, I'm almost certain no one is going to maintain these lists in the long run.
  • For the errors list, I think we can hide the internal name. These don't really appear anywhere publically in Asar (unless there's been plans to change that, like with warnings? I don't remember).
  • For warnings, on the other hand, I think only the "internal" name should be shown, since we're actually deprecating warning IDs. (Talking about that, @p4plus2 I think Asar 1.9 and 2.0 currently both still print warning IDs when a warning is thrown. That feels a bit problematic when our plan is to deprecate them. I think we should change this to print warning names instead, which would require fixing the test suite + tests. Also, I don't remember if warn enable/disable already work with warning names. Anyways, since warning IDs are already being deprecated, I do think including all this in v1.9 is crucial.)

RPGHacker avatar Dec 30 '21 20:12 RPGHacker

When I say "auto-generated" I mean:

  • I copy pasted the enum init code from errors.cpp/warnings.cpp from asar into a text editor
  • Did some manual text editing
  • Generated the html with python directly from the command line (I didn't use a script)

I kept the internal name for both for consistency.

Atari2 avatar Dec 30 '21 21:12 Atari2

@RPGHacker Added a script to automate the generation of the HTML tables.

Atari2 avatar Jan 08 '22 17:01 Atari2

Thanks, this definitely looks a lot more maintainable. I'll check it out in more detail later and then see if I can merge it.

RPGHacker avatar Jan 08 '22 22:01 RPGHacker

this is less useful now that we use the internal names instead of numeric IDs, but i guess it might still be nice to have. but the script needs to be fixed now that we don't use the numbers anymore.

also i think there are a few unused warnings and errors (in asar 2 at least). should review those aswell

randomdude999 avatar Jan 20 '24 22:01 randomdude999

i updated the script myself and reworked it a bit, will commit shortly

randomdude999 avatar Jan 20 '24 23:01 randomdude999