Clarify the Javadoc for CallStreamObserver

[leventov]

The relevant part of the current Javadoc:

grpc-java/stub/src/main/java/io/grpc/stub/CallStreamObserver.java

Lines 25 to 35 in 6b04fc1

	* <p>In any call there are logically two {@link StreamObserver} implementations:
	* <ul>
	* <li>'inbound' - which the GRPC runtime calls when it receives messages from the
	* remote peer. This is implemented by the application.
	* </li>
	* <li>'outbound' - which the GRPC runtime provides to the application which it uses to
	* send messages to the remote peer.
	* </li>
	* </ul>
	*
	* <p>Implementations of this class represent the 'outbound' message stream.

As far as I can tell, for any call, there are three implementations of StreamObserver involved:

1. Implemented by the application, on the RPC client side ('inbound')
2. Implemented by the framework, on the RPC client side ('outbound'), ClientCallStreamObserver
3. Implemented by the framework, on the RPC server side ('outbound'), ServerCallStreamObserver

I think it would be nice to clarify that. I've spent significant time trying to understand where does ClientCallStreamObserver appear, being confused by the premise that there are only two implementations of StreamObserver.

[ran-su]

Sometime, look at examples will help understand the APIs. I do agree with you some of our javadocs can be improved, and we are welcoming any contribution that helps our project. If you can send a pr to make the documentations better, we will be glad to review and merge it.

[creamsoup]

reopen this bug. Couple more clarifications are necessary as @leventov pointed out in the #6561.
@leventov, do you want to fix the other two?

[leventov]

No