Get suite doc and metadata from last suite when merging.

Metadata from earlier is preserved but values in latter ones have
precedence.

Fixes #4354.

atest/robot/rebot/merge.robot

@@ -33,6 +33,10 @@ Merge suite setup and teardown
     [Setup]   Should Be Equal    ${PREV_TEST_STATUS}    PASS
     Suite setup and teardown should have been merged
 
+Merge suite documentation and metadata
+    [Setup]   Should Be Equal    ${PREV_TEST_STATUS}    PASS
+    Suite documentation and metadata should have been merged
+
 Merge re-executed and re-re-executed tests
     Re-run tests
     Re-re-run tests
@@ -84,7 +88,12 @@ Merge ignores skip
 
 *** Keywords ***
 Run original tests
-    Create Output With Robot    ${ORIGINAL}    --variable FAIL:YES --variable LEVEL:WARN    ${SUITES}
+    ${options} =    Catenate
+    ...    --variable FAIL:YES
+    ...    --variable LEVEL:WARN
+    ...    --doc "Doc for original run"
+    ...    --metadata Original:True
+    Create Output With Robot    ${ORIGINAL}    ${options}    ${SUITES}
     Verify original tests
 
 Verify original tests
@@ -98,6 +107,8 @@ Verify original tests
 Re-run tests
     [Arguments]    ${options}=
     ${options} =    Catenate
+    ...    --doc "Doc for re-run"
+    ...    --metadata ReRun:True
     ...    --variable SUITE_SETUP:NoOperation  # Affects misc/suites/__init__.robot
     ...    --variable SUITE_TEARDOWN:NONE      #           -- ;; --
     ...    --variable SETUP_MSG:Rerun!         # Affects misc/suites/fourth.robot
@@ -173,6 +184,11 @@ Suite setup and teardown should have been merged
     Should Be Equal      ${SUITE.suites[2].suites[0].setup.name}       ${NONE}
     Should Be Equal      ${SUITE.suites[2].suites[0].teardown.name}    ${NONE}
 
+Suite documentation and metadata should have been merged
+    Should Be Equal      ${SUITE.doc}                                  Doc for re-run
+    Should Be Equal      ${SUITE.metadata}[ReRun]                      True
+    Should Be Equal      ${SUITE.metadata}[Original]                   True
+
 Test add should have been successful
     Should Be Equal    ${SUITE.name}    Suites
     Should Contain Suites    ${SUITE}    @{ALL SUITES}

doc/userguide/src/ExecutingTestCases/PostProcessing.rst

@@ -117,10 +117,19 @@ Merging is done by using :option:`--merge (-R)` option which changes the way how
 Rebot combines two or more output files. This option itself takes no
 arguments and all other command line options can be used with it normally::
 
-   rebot --merge --name Example original.xml merged.xml
+   rebot --merge original.xml merged.xml
+   rebot --merge --name Example first.xml second.xml third.xml
 
-How merging works in practice is explained in the following sections discussing
-its two main use cases.
+
+When suites are merged, documentation, suite setup and suite teardown are got
+from the last merged suite. Suite metadata from all merged suites is preserved
+so that values in latter suites have precedence.
+
+How merging tests works is explained in the following sections discussing
+the two main merge use cases.
+
+.. note:: Getting suite documentation and metadata from merged suites is new in
+          Robot Framework 5.1.
 
 Merging re-executed tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~

src/robot/result/merger.py

@@ -37,13 +37,15 @@ def start_suite(self, suite):
             old = self._find(self.current.suites, suite.name)
         if old is not None:
             old.starttime = old.endtime = None
+            old.doc = suite.doc
+            old.metadata.update(suite.metadata)
             old.setup = suite.setup
             old.teardown = suite.teardown
             self.current = old
         else:
             suite.message = self._create_add_message(suite, suite=True)
             self.current.suites.append(suite)
-        return bool(old)
+        return old is not None
 
     def _find_root(self, name):
         root = self.result.suite