Clarifies that only one serialisation mechanism is required. Clarifie…

…s dependencies required for Client RPC. (corda#4135)

* Makes it clear that only one serialisation mechanism is required. Clarifies dependencies required for Client RPC.

* Addresses review feedback.

docs/source/clientrpc.rst

@@ -11,20 +11,23 @@ Interacting with a node
 
 Overview
 --------
-You should interact with your node using the `CordaRPCClient`_ library. This library that allows you to easily
-write clients in a JVM-compatible language to interact with a running node. The library connects to the node using a
-message queue protocol and then provides a simple RPC interface to interact with the node. You make calls on a JVM
-object as normal, and the marshalling back and forth is handled for you.
+To interact with your node, you need to write a client in a JVM-compatible language using the `CordaRPCClient`_ class.
+This class allows you to connect to your node via a message queue protocol and provides a simple RPC interface for
+interacting with the node. You make calls on a JVM object as normal, and the marshalling back-and-forth is handled for
+you.
 
 .. warning:: The built-in Corda webserver is deprecated and unsuitable for production use. If you want to interact with
-   your node via HTTP, you will need to stand up your own webserver, then create an RPC connection between your node
-   and this webserver using the `CordaRPCClient`_ library. You can find an example of how to do this using the popular
-   Spring Boot server `here <https://github.com/corda/spring-webserver>`_.
+   your node via HTTP, you will need to stand up your own webserver that connects to your node using the
+   `CordaRPCClient`_ class. You can find an example of how to do this using the popular Spring Boot server
+   `here <https://github.com/corda/spring-webserver>`_.
 
 Connecting to a node via RPC
 ----------------------------
-`CordaRPCClient`_ provides a ``start`` method that takes the node's RPC address and returns a `CordaRPCConnection`_.
-`CordaRPCConnection`_ provides a ``proxy`` method that takes an RPC username and password and returns a `CordaRPCOps`_
+To use `CordaRPCClient`_, you must add ``net.corda:corda-rpc:$corda_release_version`` as a ``cordaCompile`` dependency
+in your client's ``build.gradle`` file.
+
+`CordaRPCClient`_ has a ``start`` method that takes the node's RPC address and returns a `CordaRPCConnection`_.
+`CordaRPCConnection`_ has a ``proxy`` method that takes an RPC username and password and returns a `CordaRPCOps`_
 object that you can use to interact with the node.
 
 Here is an example of using `CordaRPCClient`_ to connect to a node and log the current time on its internal clock:

docs/source/serialization.rst

@@ -39,22 +39,23 @@ weakly or untyped string-based serialisation schemes like JSON or XML. The prima
 Whitelisting
 ------------
 
-In classic Java serialization, any class on the JVM classpath can be deserialized.  This has shown to be a source of exploits
-and vulnerabilities by exploiting the large set of 3rd party libraries on the classpath as part of the dependencies of
-a JVM application and a carefully crafted stream of bytes to be deserialized. In Corda, we prevent just any class from
-being deserialized (and pro-actively during serialization) by insisting that each object's class belongs on a whitelist
-of allowed classes.
-
-Classes get onto the whitelist via one of three mechanisms:
-
-#. Via the ``@CordaSerializable`` annotation.  In order to whitelist a class, this annotation can be present on the
-   class itself, on any of the super classes or on any interface implemented by the class or super classes or any
-   interface extended by an interface implemented by the class or superclasses.
-#. By implementing the ``SerializationWhitelist`` interface and specifying a list of `whitelist` classes.
-#. Via the built in Corda whitelist (see the class ``DefaultWhitelist``).  Whilst this is not user editable, it does list
-   common JDK classes that have been whitelisted for your convenience.
-
-The annotation is the preferred method for whitelisting.  An example is shown in :doc:`tutorial-clientrpc-api`.
+In classic Java serialization, any class on the JVM classpath can be deserialized. This is a source of exploits and
+vulnerabilities that exploit the large set of third-party libraries that are added to the classpath as part of a JVM
+application's dependencies and carefully craft a malicious stream of bytes to be deserialized. In Corda, we strictly
+control which classes can be deserialized (and, pro-actively, serialized) by insisting that each (de)serializable class
+is part of a whitelist of allowed classes.
+
+To add a class to the whitelist, you must use either of the following mechanisms:
+
+#. Add the ``@CordaSerializable`` annotation to the class. This annotation can be present on the
+   class itself, on any super class of the class, on any interface implemented by the class or its super classes, or any
+   interface extended by an interface implemented by the class or its super classes.
+#. Implement the ``SerializationWhitelist`` interface and specify a list of whitelisted classes.
+
+There is also a built-in Corda whitelist (see the ``DefaultWhitelist`` class) that whitelists common JDK classes for
+convenience. This whitelist is not user-editable.
+
+The annotation is the preferred method for whitelisting. An example is shown in :doc:`tutorial-clientrpc-api`.
 It's reproduced here as an example of both ways you can do this for a couple of example classes.
 
 .. literalinclude:: example-code/src/main/kotlin/net/corda/docs/kotlin/ClientRpcTutorial.kt