Clarification on a VCS-Iface Issue

[Matt Rogers]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


On Sep 4, 2007, at 8:14 PM, Andreas Pakulat wrote:

> On 04.09.07 18:54:34, Matt Rogers wrote:
>> On Sep 4, 2007, at 8:30 AM, Andreas Pakulat wrote:
>>> On 03.09.07 21:51:39, Matt Rogers wrote:
>>>> On Sep 3, 2007, at 6:24 PM, Andreas Pakulat wrote:
>>>>> to those of you that were involved in the Vcs-Iface Design  
>>>>> decisions
>>>>> (and all others as well of course :):
>>>>>
>>>>> Did we decide that the actions like commit, add, copy, move (the
>>>>> non-Show-versions) have to work without _any_ gui at all, or are
>>>>> they
>>>>> allowed to popup dialogs when they need input like authentication
>>>>> information, or say a commit message (as import for example  
>>>>> misses a
>>>>> commit message argument)?
>>>>>
>>>>> I'm not sure wether we discussed this at all and having had a
>>>>> look at
>>>>> the svn plugin its clear that we need a decision. I don't think it
>>>>> makes
>>>>> sense to restrict these actions to non-gui-mode, as then they'd
>>>>> have to
>>>>> fail and they can't be executed without some sort of GUI running
>>>>> anyway.
>>>>>
>>>>> If we decide this I'll put a clear doc about the difference  
>>>>> between
>>>>> showwXXX and XXX into the api docs. Currently I'm leaning towards
>>>>> something along the lines (assuming we allow gui from XXX  
>>>>> methods):
>>>>>
>>>>> showXXX - allows the user to input the parameters for the action
>>>>> to be
>>>>> executed, always shows this GUI
>>>>>
>>>>> XXX - tries to execute the action without user-interaction, but  
>>>>> will
>>>>> create a dialog if needed for input of missing information
>>>>>
>>>>> Andreas
>>>>
>>>> This is where I dislike having two different sets of API that  
>>>> perform
>>>> the same thing. It was said that this is for scriptability.  
>>>> However,
>>>> doesn't a platform app have to be running to be able to run scripts
>>>> anyways. Why can't we just normalize it so that it does what you
>>>> suggest in the XXX case and remove the showXXX versions of the same
>>>> functions?
>>>
>>> I was about to agree with you, but then I remembered why we added  
>>> the
>>> showXX methods in the first place: To make it possible to  
>>> retrieve the
>>> result from the action, instead of displaying it to the user.  
>>> This of
>>> course doesn't make sense for all actions, for example
>>> add/remove/move/copy/commit and possibly others. But for things like
>>> stat(), diff() and maybe a few others this is a real good thing,
>>> because
>>> those can then be used from other parts of KDevelop, for example the
>>> project tree can ask the project wether it has VCS and then just
>>> ask the
>>> VCS for status of all the dirs/files.
>>
>>> So how about removing the showXXX methods where it doesn't make  
>>> sense,
>>> i.e. the result/return value of the job is trivial and leave it  
>>> in for
>>> others, along with my suggestion above, that any XXX/showXXX  
>>> method is
>>> allowed to ask for needed parameters.
>>>
>>> Andreas
>>>
>>
>> We should always retrieve a result. Don't we always need to know
>> whether something succeeded or not? Whether or not we display it to
>> the user is up to the user of the API. We need to remove all of the
>> showXXX methods. They're redundant.
>
> I don't think they are. Those are specifically to let the user see  
> the result
> instead of just fetching it and eventually doing something with it.  
> For
> cases where the user of the API wants the developer see the result of
> the diff, the showXXX methods can be used, which saves the user of the
> API some code to write that would put the diff into a diff-viewer.  
> This
> code would be redundant for _every_ user of the API that wants to show
> the diff to the user and that redundancy is avoided by having showXXX
> methods.
>

Ok, so diff is a valid use case for these show methods. Perhaps we  
can rename them displayXXX instead? Do you have other valid use-cases  
for other methods? Diff is the only one where I am aware of where it  
makes sense. Perhaps log as well.

Another idea:
What about just having the XXX methods in most cases displaying these  
things in a tab in the text editor? We provide a virtual protected  
function that allows the user of the API to customize how the display  
is handled, and the XXX function calls it. This is similar to how  
it's handled in QItemDelegate and that's basically the same sort of  
functionality we're talking about here.

Thoughts?

> The implementation of these methods should of course use the normal  
> XXX
> methods and not re-implement everything from scratch as is done
> currently in the svn plugin.
>
> Andreas

Agreed.
- --
Matt


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (Darwin)

iD8DBQFG3g6oA6Vv5rghv0cRAr6MAJ9Xaom3BSrQqi4Tob5RZVRa0KrbiQCgq+Av
IpvmkFfhcnyOrqbqboaL+2k=
=ZfQp
-----END PGP SIGNATURE-----