[Authentication] Small specification improvements

[Michael Leupold]

Hi,

in addition to what Eckhart already posted to this list, I noted down some 
additional things which I think need a bit of refinement, mostly corner cases 
where error handling needs additions (in my opinion):

1. When using Prompt objects there's currently no way to signal a specific 
error to the caller - though most calls can use an "invalid" return value to 
indicate failure:
- CreateCollection/CreateItem => '/'
- Unlock/Lock => item's ObjectPath is not in the unlocked/locked array

Usually that's not much of a problem, ie. if creating or unlocking a 
collection fails the caller could just ask the user what to do ("Saving your 
mail password failed. Do you want to retry?"). There is however one case this 
does not make sense in: an operation failing because the user cancelled it.

Possible solution: the org.freedesktop.Secret.Prompt.Completed signal gets an 
additional "OUT Boolean cancelled" argument.

2. There might be other reasons why calls fail in addition to the ones 
mentioned in chapter 14 (eg. resource limitations). Is it alright to add 
something along the lines "In addition to the errors mentioned here, clients 
should be prepared to receive any of the org.freedesktop.DBus.Error errors"?

What do you think?

Regards,
Michael