Jump to content

  •  





Small thought of a documentation issue that has been there for more than 9 years.

Posted by jaBote, 07 June 2014 · 1034 views

While I'm certain nobody of the people who caused this in more or less extent will read this blog post because of the fact that eAthena community has extensively changed since 2005 (9 years ago) to the point none of current Athena based communities are still there, I just had to vent it off and give a small advice to every people: report all possible issues you may have found on our bug tracker! Seriously! Devs and documentation makers can't do everything and they'll surely make mistakes, it's up to you (the final user) the amount of time that the errors are kept and thus, the amount of damage they can potentially cause to you and the whole community.

The problem I found and fixed could be easily classified as a serious one, because of the amount of people that may have made the same mistake I did on a script I couldn't test and just had passed Haru's script checker before giving it to a requester. I mean bugreport: #8226 and the misleading documentation for script command addtimercount, which has been fixed on the 1-line commit 60e3678. All of the following is just the same note I added just to let everyone know that this could even have been solved 9 years ago since my honest opinion is that we can't afford that as community:

I'd like to give a small shoutout both for the documentation makers and the scripters who have been using this script command because this serious documentation error has been there for as far as I've been able to track this file (eAthena SVN r2397) and its precursor (eAthena SVN r1891: doc/Script_Commands.txt, since May 30, 2005) when the source required it has always been wanting it on that order (proof). Its precursor on the same revision (eAthena SVN r1891: doc/script_ref.txt) had it on the right order since eAthena SVN r1 (proof, and src/map/script.c at that time).

I'm sure we all at Hercules and all predecessors until eAthena r1891 are very grateful that we have this documentation, and it isn't just a documentation maker mistake (since we can always make mistakes) but it's not a mistake but a fault for every scripter that has used that script command and received the server side warning (if it had) for inappropriate arguments order since then and haven't reported it or just fixed it for themselves because I refuse to believe that this script command (of moderate usefulness) hasn't been used by anybody in more than 9 years.


I'd like to honestly thank Fredzilla's efforts to make a proper documentation again (since previous one was illegible as you can see). And remember, don't shut it up on these issues: remember that even if you own a private server and fix it yourself, you got a full server package from us (any eAthena or subsequent emulator) for free, from which you may even get profit! We don't want the money, but what restrains you to pay it back to us on cute, nice bug reports even if it's because of documentation inaccuracies?

Just my two cents.




That's such an odd way to execute a command, though.

*addtimercount "NPC::OnLabel",<ticks>;

 

I feel like the code should be written the way it was previously described in the documentation in this case, particularly because it would seem more reasonable to add a numerical value to a command called "addtimercount" when that's how most of our script commands (that take integer values) work. It's not like it's an option flag; it's literally the primary operation of the script command.

 

Regarding the nine-year documentation/code error, kudos to anyone who's attempted to use this script command and/or circumvented using it with their own method(s).

That's such an odd way to execute a command, though.

*addtimercount "NPC::OnLabel",<ticks>;

 

I feel like the code should be written the way it was previously described in the documentation in this case, particularly because it would seem more reasonable to add a numerical value to a command called "addtimercount" when that's how most of our script commands (that take integer values) work. It's not like it's an option flag; it's literally the primary operation of the script command.

 

Regarding the nine-year documentation/code error, kudos to anyone who's attempted to use this script command and/or circumvented using it with their own method(s).

 

I said that at the topic in which I found the scripting doc flaw (along with my totally nullity on scripting without testing):

I'll report this as a bug just after I make this reply. Common sense is that the order in which the script command wants it will be reversed to match the other script command's. You can change it if you want it
working now, but be wary it may change over time to match the other command.

 

But this is as inherited from jAthena, as you can see on eAthena r1. I'd honestly keep it the documentation way since it makes way more sense to me too (and it'd be the same arguments as of addtimer, too), but preferred to follow Pan's instruction since I'm not (a big deal of) a coder myself.

 

P.S.: The people that stumbled upon it and got it circumvented deserve that their script get broken IMHO <insert devil smilie here>.