Rework developer guide considerations

Signed-off-by: Guillaume Lambert <guillaume.lambert@orange.com>
Change-Id: I06d99ff21b9c4d197dde1e667ab435e1d3a8391f

diff --git a/docs/developer-guides/tests/considerations.rst b/docs/developer-guides/tests/considerations.rst
index 03480ad80b8c7911e59cdf5084f4f652b7045b65..1a9abf528ec99fc42a7103b66244574603b7e782 100644 (file)
--- a/docs/developer-guides/tests/considerations.rst
+++ b/docs/developer-guides/tests/considerations.rst
@@ -7,9 +7,9 @@ Considerations on Tests
 PowerMock
 =========
 
-Avoid using PowerMock, if you can at all. It's black magic with special
+Avoid using PowerMock, if you can at all. It is black magic with special
 class loaders to mock static and what not really is a band aid for
-existing legacy untestable code. Consider refactoring the respective
+existing legacy code impossible to test. Consider refactoring the respective
 OpenDaylight code to be tested first, if you can.
 
 Also think twice if you're using PowerMock on existing utility classes -
@@ -18,7 +18,7 @@ utilities that deals with the DataBroker (that's wrong, common shared
 utilities should be used). Many of these utility classes have static
 methods (that's wrong, they should get a DataBroker passed to their
 constructor, see
-org.opendaylight.genius.datastoreutils.SingleTransactionDataBroker,
+``org.opendaylight.genius.datastoreutils.SingleTransactionDataBroker``,
 imagine there is no static there, that's again just for legacy). When
 writing a test, you could be tempted to use PowerMock on such static
 utility methods. That's wrong though - you should just let the code
@@ -33,13 +33,13 @@ whatever framework), because there is a reasonably light weight test
 implementation of the entire persistence subsystem that is well suited
 for use in tests. You can easily use it by having your \*Test class
 extends
-org.opendaylight.controller.md.sal.binding.test.ConstantSchemaAbstractDataBrokerTest
-and calling getDataBroker(), or just using the
-org.opendaylight.controller.md.sal.binding.test.DataBrokerTestModule's
-static dataBroker() method.
+``org.opendaylight.controller.md.sal.binding.test.ConstantSchemaAbstractDataBrokerTest``
+and calling ``getDataBroker()``, or just using the
+``org.opendaylight.controller.md.sal.binding.test.DataBrokerTestModule``
+static ``dataBroker()`` method.
 
 NB that if you use the above, then (obviously) it makes no sense
-(anymore) to use @RunWith(MockitoJUnitRunner.class) and @Mock DataBroker
+(anymore) to use ``@RunWith(MockitoJUnitRunner.class)`` and ``@Mock DataBroker``
 and the transactions.
 
 Mockito
@@ -47,7 +47,7 @@ Mockito
 
 Using Mockito can be fine - but keep an eye on how lines in your test
 are pure "Mockito infrastructure" related VS how many are "actually
-really test code". Do not "overmock"; for example, there is absolutely
+really test code". Do not "over-mock"; for example, there is absolutely
 no point in mocking implementations of the interfaces YANG code
 generations used e.g. for RPC input & output objects - just use the
 \*Builder, like "real" code would. Also of course you would never Mock
@@ -76,7 +76,7 @@ Mockito:
        ...
    }
 
-If YourRpcService has other methods than just someOperation(), you can
+If ``YourRpcService`` has other methods than just ``someOperation()``, you can
 use a variant of "partial mocking":
 
 .. code:: java
@@ -120,10 +120,10 @@ necessarily data objects in Java objects generated by YANG binding, a
 number of projects use the `vorburger/xtendbeans
 library <https://github.com/vorburger/xtendbeans>`__.
 
-The org.opendaylight.mdsal.binding.testutils.AssertDataObjects provides
+The ``org.opendaylight.mdsal.binding.testutils.AssertDataObjects`` provides
 tight integration of this into OpenDaylight, including the
-org.opendaylight.mdsal.binding.testutils.XtendBuilderExtensions, which
-makes for a very readably syntax.
+``org.opendaylight.mdsal.binding.testutils.XtendBuilderExtensions``, which
+makes for a very readable syntax.
 
 Component Tests
 ===============