Dox, It is no work at all.
I see all kinds of invalid arguments passing by here and there. I think it is no work at all to keep the Dox current.
Whenever you change an existing method you change the dox accordingly. Whenever I do a commit, I almost always look at the diff before that, that is where I clean left overs from failed experiments, fix whitespaces, make a small optimalisation and adjust the apidox comments….
There is a lot of helpfull kde documentation, without it I would have never put X-DCOP-ServiceType=Unique in my .desktop while converting RSIBreak to a KUniqueApplication. Only because it was mentioned in the KDE API Reference.
I imagen the same will happen for potential new contributors of KMyBigApp. Really, it is no work at all. Just do it.
No argument isn’t a valid argument either… And “Whenever you change an existing method you change the dox accordingly.” isn’t the same thing as “Whenever I do a commit … adjust the apidox comments..” at all, on the contrary. If you adjust the apidox comments one commit you don’t change the dox when you change the methods. Anyway, why can’t my editor keep the arguments list in the apidox up-to-date for me? This is a computer, it’s supposed to cut down on repetitive work.
You at least need to write some description for the parameter, so that can not be automated, so you are only talking about the automating the change of the name of a variable? That would be dangerous if people forget to adjust the description, if you change a parameter, it is likely you also changed the behaviour.
The generation of a comment in kdevelop is possible with ctrl-alt-s if I recall correctly (changed it to something more logical).