Please document deprecation of features

[cout]

I have found a few features that are recommended in the manual but which produce a deprecation warning:

• table
• endif to end a while
• math round
• prefixing asar commands with @ (docs suggest to use @asar 1.9 instead of math pri )
• Using asar 1.9 ("invalid version number")

[cout]

Related - the warning message for math round off suggests I should use asar 1.9 to fix the deprecation warning. Using asar 1.9 produces:

error: (Einvalid_version_number): Invalid version number. [asar 1.9]

Instead, I need to use asar 1.90. Is this intended?

[RPGHacker]

If I remember correctly, the deprecations are documented in the changelog. Personally, I'd like to avoid adding the deprecation notes to the documentation, since these commands will just disappear entirely from it in Asar 2.0 anyways, so in some sense, this would just be an extra maintenance effort for us with very little benefit. I feel like having just the deprecation warnings and the deprecation notes in the changelog should be enough, but I dunno, maybe other people disagree?

As for the the the "1.9" thing, yeah, I do believe that's an oversight in the warning message and should be fixed. Or maybe more accurately, I'd say this a bug with the asar command itself. IMO, asar 1.9 should compile fine and not throw an error.

[cout]

As a user, I use the documentation as a guideline for how to write asm. It is confusing to me for the documentation to recommend I write my code one way, only to find the tool recommends I write it a different way.

If users are expected to read the changelog to know which features are deprecated, I think you will find that most users won't bother, and there will be a lot of confusion when users try to upgrade, only to find features they are using have been removed. This could be avoided by changing the documentation to make the same recommendation as the assembler (something that needs to be done eventually anyway once the features are removed).

[RPGHacker]

I think you will find that most users won't bother, and there will be a lot of confusion when users try to upgrade, only to find features they are using have been removed.

I can definitely see your point here. Though on the other hand: Won't this only be the case when they explicitly ignore warnings given by the assembler? In my opinion, when something goes wrong as the result of consciously ignoring warnings, the fault can only lie with the person doing so. So at least in this specific case, I still wouldn't say the documentation were to blame.

Still, I see your point about how the documentation shouldn't encourage using deprecated functionality, so I do think there's some merit in adding deprecation notes to it. I guess it's primarily a matter of actually doing it, which could be quite time consuming. Ideally, it should also be done in a way that won't cause headaches down the line when merging branches. An alternative solution could be to not add deprecation notes to the manual, but to rather remove all deprecated functionality from the manual outright, which might at least make merges easier (since the newer Asar version would have to delete all those entries from the manual, anyways).

[randomdude999]

documented all 1.9 deprecations in the manual (well, the ones about features that were documented in the manual in the first place, that is).