Add documentation comments to methods showing which units are returned

[Sword-Smith]

trafficstars

When using for example the method ICoinService.GetBalance(), it would be nice to be able to read from the function description (formally: "documentation comments") which units a function returns. Is it satoshi or bitcoins? I believe it is bitcoins, like the RPC, but that ought to be appear from the documentation, in my opinion.

Feel free to assign this issue to me if you think it is a good idea.

[moodmosaic]

That's usually a good idea. So in your example, instead of a decimal we could return a user-defined type, e.g. btc or Bitcoin and then you'd have the information you want embedded in the types themselves instead of docs.

My concern with docs and comments is that they can easily become stale, outdated, etc.

Type-driven development is more common in languages like Haskell, F#, OCaml, etc. I'm not sure it's that's common in languages like Java or C#, see Primitive Obsession.

Happy to discuss further on this, but keep in mind that it'll be a massive effort to go through each and every interface member and add types/comments to it.