Add example for how to use the RPC functionality

[maxekman]

I decided to create a full example of how to use the RPC functionality. This could really benefit others showing a clear example of the full process involved.

Earlier I opened an issue in this other library (https://github.com/hashicorp/net-rpc-msgpackrpc) as I thought their functionality was a duplication of yours. He didn't know your library implemented RPC as the documentation was lacking in that area. This example will help him understand how to use it.

I will now go on and use your RPC in my own application (as discussed in an earlier issue.) Thanks!

[ugorji]

The RPC functionality is documented sufficiently IMO.

I agree that we didn't write an example, but I'm cautious about adding simplistic examples beyond documenting that the API exists. It's hard to know where to draw the line, so we instead do not add detailed examples, but show a typical usage model.

If you look at the hashicorp library, it's very empty: https://github.com/hashicorp/net-rpc-msgpackrpc/blob/master/msgpackrpc.go . It's a very short 1-file library that just implements one-liner functions that forward to my go/codec functions, and a 4-liner Dial helper function mimicking a convenience function available in encoding/json. IMHO, it adds ZERO value as a library. So the hashicorp folks definitely knows how to use the go/codec rpc library, as they implemented an unnecessary facade over it.

All his rpc-related functions are documented, both in the top-level doc.go, and in the README.

See:

http://godoc.org/github.com/ugorji/go/codec

• See example in the Usage Model for how to use rpc functionality
• See Msgpack specific notes
• See RPC functionality

[maxekman]

Fair enough, but I still think an example like this adds a lot of value to new users without cluttering the documentation page (as it resides in a collapsed section.) It also contains only minimal code to make it complete.

The example is in it's own source file and does not clutter the main code base, which could have been an issue.

You should really value open source documentation contributions as that really comes from a perceived lack of thereof (individual to each user of course, me in this case.) If I had made a pull request with a feature I can understand your hesitation, but for documentation it can't really be too clear IMO.

Best, Max

[ugorji]

Hi Max,

I don't want you to take this the wrong way. I value all types of open-source contribution, documentation or code. But it has to fit in with the goals, because I still have to maintain it. It's very unfair to suggest I don't.

Earlier on, I decided against including examples, and opted for ensuring that the usage model in pseudo-code is complete. The goal was to have concise and to-the-point expert documentation, versus detailed. For example, for RPC support, I state that we support net/rpc functionality, and show how to use that functionality with my library in the usage notes. I don't walk users on how to use net/rpc functionality (which is what your example does). I only show users the relevant parts where ugorji/go/codec is used (in the usage notes, which are clear).

Note that the hashicorp library doesn't add any value to the examples either - they just expose new function names.

Note that the http://golang.org/pkg/net/rpc/jsonrpc/ doesn't add any examples either - they just expose the function names.

To re-iterate, I value contributions. If you tell me:

• I didn't see the docs on how to use net/rpc. What about including the usage notes for rpc under the rpc section of the documentation, then I can talk to that (I had it that way for a while, and played with different ways of exposing the usage in a concise form, before deciding to just keep all usage models in one place).

[maxekman]

Thanks for the clear explanation of your thinking behind the documentation. It feels like you have good reasoning behind your choices. I'm not at all taking it the wrong way, I just wasn't aware of your goals of being to-the-point.

I'm not using, or considering to use, the hashicorp library, I wanted to consolidate the use of msgpack-rpc to your library to avoid duplication in the Go eco-system.

Regarding the docs for net/rpc I think it's lacking. The basic usage is good but anything else is not well documented. During my research on how I would do RPC in Go I have seen a lot of users (probably new to the language like me) that are looking for examples and more help on how to put the pieces together. I'm in no way saying that your library should provide for that, but that was my only reason for forking your library and creating a documented example instead of just taking 5 minutes and implementing it directly in my app.

Anyway, thanks again for the nice library, I really like it!