Documentation for IamDataFrame.rename() is misleading/incomplete

[phackstock]

The way that the documentation of the IamDataFrame.rename() method is currently written, does not mention that in case of "variable" as the dimension and the renaming mapping containing multiple variables that have the same target, aggregation is performed.
For example:

"variable": {'Final Energy|Electricity': "Final Energy", 'Final Energy|Heat': "Final Energy"}

computes a variable Final Energy as the sum of Final Energy|Electricity and Final Energy|Heat.
I have not found a mention of this in the docs.