Clarify and fix documentation of canrpptest command

diff --git a/rpp-test-sw/commands/cmd_can.c b/rpp-test-sw/commands/cmd_can.c
index a5833c205cf7279a17f8c237e97bd8b94198499e..fd2f342d05b6592f249a016673a758ddb8391b2b 100644 (file)
--- a/rpp-test-sw/commands/cmd_can.c
+++ b/rpp-test-sw/commands/cmd_can.c
@@ -1005,102 +1005,106 @@ cmd_des_t const cmd_des_can_test={
     "\n"
     "### Description ###\n"
     "\n"
-    "This command tests all CAN functions in the RPP library. It does those\n"
-    "particular tests:\n"
+    "This command tests all CAN functions in the RPP library. It requires\n"
+    "the CAN1 and CAN2 connectors to be connected with HW loopback. The\n"
+    "following tests are performed:\n"
     "\n"
-    "1.  Test of the rpp_can_init(), rpp_can_write() and rpp_can_read() functions.\n"
+    "1.  Test of `rpp_can_init()`, `rpp_can_write()` and `rpp_can_read()` functions.\n"
     "\n"
-    "    At the beginning, the CAN bus is initialized with manually specified and\n"
-    "    verified CAN bit timing parameters. Then a message is sent on the CAN1 and is\n"
-    "    received on the CAN2. Finally the received message is compared with the sent one.\n"
-    "    If the transmissions fails, reception exceeds a timeout or the sent and\n"
-    "    received messages do not match, the command prints the appropriate error\n"
-    "    code.\n"
+    "    At the beginning, the CAN bus is initialized with hardcoded (and\n"
+    "    verified) verified CAN bit timing parameters. Then a message is\n"
+    "    sent to the CAN1 interface and received from CAN2. The received\n"
+    "    message is compared with the sent one. If the transmissions fails,\n"
+    "    reception exceeds a timeout or the sent and received messages\n"
+    "    differ, the command prints an appropriate error code.\n"
     "\n"
-    "2.  Test of the CAN bit timing parameters calculation.\n"
+    "2.  Test of CAN bit timing parameters calculation.\n"
     "\n"
-    "    This test subsequently initializes the CAN bus to a baudrates 125k, 250k\n"
-    "    and 500k. For each one of them a message is sent on CAN1 and received on CAN2.\n"
-    "    Finally the received message is compared with the sent one like in a test (1).\n"
-    "    If the initialization, transmission, reception or comparison fails or\n"
-    "    if the reception timeout is reached, an appropriate error code is\n"
-    "    printed.\n"
+    "    This test subsequently initializes the CAN controller to baudrates\n"
+    "    125k, 250k and 500k. For each one of them a message is sent to\n"
+    "    CAN1 and received from CAN2. The received message is compared with\n"
+    "    the sent one like in test 1. If the initialization, transmission,\n"
+    "    reception or comparison fails or if the reception timeout is\n"
+    "    reached, an appropriate error code is printed.\n"
     "\n"
     "3.  Test of the behavior of transmission request overwriting.\n"
     "\n"
-    "    The CAN bus is initialized like in the test (1). A message A transmission\n"
-    "    request is posted on CAN1 by calling rpp_can_write() and right after that\n"
-    "    another message B transmission request is posted on CAN1 by another call of\n"
-    "    the rpp_can_write(). A message B is received on CAN2, because the second request\n"
-    "    came so quickly, that it overwrote the first one. The sent and received messages\n"
-    "    are compared to verify that the transmission was correct.\n"
+    "    The CAN controller is initialized as in test 1. A transmission\n"
+    "    request for message A is made on CAN1 by calling `rpp_can_write()`.\n"
+    "    Right after that another transmission request for message B is\n"
+    "    made on CAN1 by another call to `rpp_can_write()`. A message B is\n"
+    "    received on CAN2, because the second request came so quickly, that\n"
+    "    it overwrote message A in the TX buffer. The sent and received\n"
+    "    messages are compared to verify that the behavior was correct.\n"
     "\n"
-    "    If the initialization, transmission, reception or comparison fails or\n"
-    "    if the reception timeout is reached, an appropriate error code is\n"
-    "    printed.\n"
+    "    If the initialization, transmission, reception or comparison fails\n"
+    "    or if the reception timeout is reached, an appropriate error code\n"
+    "    is printed.\n"
     "\n"
     "4.  Test of the TX request pending flag detection.\n"
     "\n"
-    "    The CAN bus is initialized like in the test (1). A message is transmitted\n"
-    "    on the CAN1 and the test waits for the TX pending flag to be set, which\n"
-    "    signalizes that there is a message transmission request pending. After the\n"
-    "    flag has been set, the test waits for its clearance, which means that the\n"
-    "    message has been sent. The test measures, how many flag test cycles passed,\n"
-    "    until the flag has been cleared. This value is then presented as a time.\n"
-    "    At the end, the message is received on the CAN2 and is compared with the\n"
+    "    The CAN bus is initialized like in test 1. A message is\n"
+    "    transmitted on CAN1 and the test waits for the TX pending flag to\n"
+    "    be set, which signalizes that there is a message transmission\n"
+    "    request pending. After the flag has been set, the test waits for\n"
+    "    its clearance, which means that the message has been sent. The\n"
+    "    test measures, how many flag test cycles passed, until the flag\n"
+    "    has been cleared. This value is then presented as time. At the\n"
+    "    end, the message is received from CAN2 and it is compared with the\n"
     "    sent message for verification.\n"
     "\n"
     "    If the initialization, transmission, reception or comparison fails or if\n"
     "    timeout is reached while waiting for the flag set/clear or receive timeout\n"
     "    is reached, an appropriate error code is printed.\n"
     "\n"
-    "5.  Test of the message received (RX) indicator.\n"
+    "5.  Test of the message received (RX) indication.\n"
     "\n"
-    "    The CAN bus is initialized like in the test (1). A message is transmitted\n"
-    "    on the CAN1. The test then waits for the RX indicator to be set, which\n"
-    "    indicates that a message has been received. The message is picked up by\n"
-    "    the rpp_can_read(). This should clear the indicator, which is tested. Finally\n"
-    "    the received messages is compared with the sent one.\n"
+    "    The CAN bus is initialized like in test 1. A message is\n"
+    "    transmitted on CAN1. The test then waits for the RX indication to\n"
+    "    be set, which indicates that a message has been received. The\n"
+    "    message is picked up by calling `rpp_can_read()`. This should\n"
+    "    clear the indicator, which is tested. Finally the received\n"
+    "    messages is compared with the sent one.\n"
     "\n"
     "    If the initialization, transmission, reception, message comparison or indicator\n"
     "    test fails or if timeout is reached while waiting for the flag set, the\n"
     "    appropriate error code is printed.\n"
     "\n"
-    "At the end the CAN bus is reset and left with the configuration from test (1).\n"
-    "Those tests assumes the CAN1 and CAN2 to be connected in HW loopback.\n"
-    "Any previous configuration is canceled, but is not deleted, so any following\n"
-    "call of caninit command will restore the CAN bus to previous configuration.\n"
+    "At the end the CAN bus is reset and left with the configuration from\n"
+    "test 1. Any previous configuration is canceled, but is not deleted, so\n"
+    "any following call of `caninit` command will restore the CAN bus to\n"
+    "previous configuration.\n"
     "\n"
     "For error codes description refer please the API documentation for the rpp-test-sw.\n"
     "\n"
     "### Example ###\n"
     "\n"
     "    --> canrpptest\n"
-    "This is a test for RPP CAN library functions:\n"
-    "Test of simple message transmission and reception.\n"
-    "  CAN bus Initialization...OK\n"
-    "  Transmission and reception...OK\n"
-    "---\n"
-    "Test od automatic CAN bit timing calculation.\n"
-    "  Baudrate: 125000: OK\n"
-    "  Baudrate: 250000: OK\n"
-    "  Baudrate: 500000: OK\n"
-    "---\n"
-    "Test of transmission request rewritting.\n"
-    "  CAN bus Initialization...OK\n"
-    "  TX request rewritting...OK\n"
-    "---\n"
-    "Test of TX request pending flag detection.\n"
-    "  CAN bus Initialization...OK\n"
-    "  TX request pending flag behavioral: OK, time: 256 cycles.\n"
-    "---\n"
-    "Test of RX indicator.\n"
-    "  CAN bus Initialization...OK\n"
-    "  RX indicator behavioral:\n"
-    "OK, time: 0 cycles.\n"
-    "---\n"
-    "Reset the CAN bus.\n"
-    "  CAN bus Initialization...OK\n",
+    "    This is a test for RPP CAN library functions:\n"
+    "    Test of simple message transmission and reception.\n"
+    "          CAN bus Initialization...OK\n"
+    "          Transmission and reception...OK\n"
+    "    ---\n"
+    "    Test of automatic CAN bit timing calculation.\n"
+    "          Baudrate: 125000: OK\n"
+    "          Baudrate: 250000: OK\n"
+    "          Baudrate: 500000: OK\n"
+    "    ---\n"
+    "    Test of transmission request rewritting.\n"
+    "          CAN bus Initialization...OK\n"
+    "          TX request rewritting...OK\n"
+    "    ---\n"
+    "    Test of TX request pending flag detection.\n"
+    "          CAN bus Initialization...OK\n"
+    "          TX request pending flag behavioral: OK, time: 256 cycles.\n"
+    "    ---\n"
+    "    Test of RX indicator.\n"
+    "          CAN bus Initialization...OK\n"
+    "          RX indicator behavioral:\n"
+    "    OK, time: 0 cycles.\n"
+    "    ---\n"
+    "    Reset the CAN bus.\n"
+    "          CAN bus Initialization...OK\n",
     CMD_HANDLER(cmd_do_can_test_functions), (void *)&cmd_list_can
 };