KAction: kill all convenience methods

[Andreas Hartmetz]

The list of methods is quite long. It's harder than necessary to find
what you are looking for and that makes the API harder to use. About
the 5% that need non-default parameters: it's basically
act.setDefaultShortcut() vs. act.setShortcut(DefaultShortcut).
ATM there are 4 convenience methods for every type of shortcut a
KAction can have (local and global), 8 total. To illustrate, here is
what they do for local shortcuts:
activeShortcut() -> shortcut()
setActiveShortcut() -> setShortcut(ActiveShortcut)
defaultShortcut() -> shortcut(DefaultShortcut)
setDefaultShortcut() -> setShortcut(DefaultShortcut)
In the out-of-date API docs on the web, "active" is still called "custom".
You can trust me or grep some KDE source tree yourself to see that
everything except setShortcut() is rarely used.
For every new kind of trigger we'd need another 4 convenience methods
to maintain consistency. There will be at least mouse gestures and
maybe more new triggers...
Better ordering and grouping of related functions in the docs could
help, too, if the convenience methods should stay.

Cheers,
Andreas

2006/12/11, Matt Rogers <mattr at kde.org>:
> On Sunday 10 December 2006 19:52, Andreas Hartmetz wrote:
> > Hi!
> >
> > I have a suggestion for KAction: remove all the convenience
> > set<X><Y>Shortcut / get<X><Y>Shortcut methods. There is a long list of
> > them and they make reading the documentation very _in_convenient. I
> > think they should die. >95% of use cases are well served by the normal
> > version of the calls with default parameters. When KAction gets more
> > triggers, the clutter could get worse still.
> > Protests?
> >
> > Cheers,
> > Andreas
>
> The purpose of convenience methods is to make it easier on the user to use a
> piece of API. How does removing these convenience methods affect the ease of
> use of the API?  What about the other 5% of the use cases that aren't well
> served by the normal version of the calls with default parameters? What are
> they supposed to do?
>
> So far, I'm not convinced.
> --
> Matt
>