Improve ChannelKeys TODOs

[TheBlueMatt]

We currently have TODOs in public documentation, which isn't OK, but also we should replace the with real documentation before the next release.

[TheBlueMatt]

Also, we should probably fix up the APIs to be sensible post-559 pre-0.0.11.

[ariard]

We should make signing function as pure function do avoid any side-effect and return a Result<Signature,Error> to propagate back error to caller.

See #559 (comment) and #562 (comment)

[TheBlueMatt]

The ChannelKeys stuff should never be pure functions - many cases of channel keys require internal state to enforce that we dont eg sign two different local commitment transactions. They should, of course, return Result<>s, though maybe I misunderstood your point.

[valentinewallace]

Should this have been closed by #598?

[TheBlueMatt]

Yep!