search

congo-cc / congo-parser-generator

The CongoCC Parser Generator, the Next Generation of JavaCC 21, which in turn was the next generation of JavaCC
https://discuss.congocc.org/
Other
38 stars 11 forks source link

Remove deprecated Method #24

Closed stbischof closed 5 months ago

stbischof commented 1 year ago

Could we remove this or there is it needed?

https://github.com/congo-cc/congo-parser-generator/blob/6a9d307b8e83a14c2900dda7f8cd32b80f444708/src/templates/java/Node.java.ftl#L472-L478

revusky commented 1 year ago

Well, it's not really needed. The origin of this is that, for some reason (probably a momentary lack of mental clarity) I had a separate method in the Node interface called getTokenType, which just returned null unless this was actually a Token and otherwise returned token.getType(). As far as I can tell, now that I think about it, there was never any real reason for this separate getTokenType API to exist. But, it did, and that was the API throughout the entire JavaCC21 history.

So, at some point, I realized that there was no real need for a separate getTokenType() API, that it might as well just be getType() throughout. But I just traced back the history. I was surprised to realize that I only made this change, at the very end of January. So I changed it to getType() but I left getTokenType() as a courtesy basically, in case anybody was using that. But then it occurred to me some days after that that getTokenType() should really be marked as deprecated and I should just tell people there to use getType(). So I marked it as deprecated on 11 February. (I just now checked the history of all this quickly.)

So, the basic question is how long something should be marked as deprecated before it is finally removed. Well, in this case, it's been 2 months. I think I'll just leave it there for somewhat longer and then remove it, maybe in a few months. Most likely nobody is even using it, but I'll follow some more or less sensible procedure on these things anyway. Maybe six months is a reasonable period of time for something marked deprecated to be removed. I don't honestly know. I did remove various deprecated things transitioning to the Congo naming. All those generated constructors that took Reader and InputStream and such. But those were marked as deprecated for a good long time before I removed them. Of course, the biggest thing was I got rid of all support for the legacy syntax. You have to use the new streamlined syntax now. But that was warned for a long time too. And besides, that is doing people a favor anyway! LOL.

stbischof commented 1 year ago

I really appreciate your description. this content helps a lot to understand.

So i always would suggest to set the "since" attribute and also the for Removal, so that its later easier to understand why this still exists.

revusky commented 5 months ago

FYI, I just removed (actually commented out for now, but probably will totally remove soon) all the deprecated methods in Node.java.ftl. (Including the one you brought up.) But that is mostly all these things like addChild and removeChild, which was a naming I went for back in 2008 or so, when the project was called FreeCC. You now one just uses add and remove and so on, which is really just the API in java.util.List. BTW, I think that the corresponding APIs in both Python and C# should just be set up to follow the principle of least surprise as well.