asar
asar copied to clipboard
Add documentation about error/warnings IDs along with the error message
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.
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.)
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.
@RPGHacker Added a script to automate the generation of the HTML tables.
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.
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
i updated the script myself and reworked it a bit, will commit shortly