Is there any documentation regarding the use of war elephants in battles?

According to legend I think it is in Josephus Simon the last survivor of the five sons of Mattathias of the Maccabees falls in battle by thrusting a spear into the belly of war elephant on which he thought the king was riding, the elephant fell on him crushing him death.

War elephants were constantly used in south Asia for over 2000 years. The last use was by Thai and Vietnamese forces in the late 1800s. Use of elephants for logistics continued into the 20th century.

Some rulers had thousands of war elephants.

Either elephants made important contributions to victory for thousands of years or every southern Asian ruler was a fool for thousands of years.

In the Battle of Heraclea (280 BC), Pyrrhus of Epirus used elephants decisively against the Romans. The trick for him was to use them as reserve forces.

This is from the Wiki article:

Unable to make any significant gains in action, Pyrrhus deployed his war elephants, held in reserve until now. The Roman cavalry was threatening his flank too strongly. Aghast at the sight of these strange and brooding creatures which none had seen before, the horses galloped away and threw the Roman legion into rout. (The Romans subsequently called elephants "Lucanian oxen", after the location of this first encounter.). Pyrrhus then launched his Thessalian cavalry among the disorganized legions, which completed the Romans' defeat. The Romans fell back across the river and Pyrrhus held the field.

It's the first time Romans saw elephants though :)

The Battle of Ipsus (301 BC) is also worth mentioning. Antigonus Monophthalmus and his son Demetrius Poliorcetes commanded a strong infantry army, but their 75 elephants were a bit short for Seleucus 400-480.

Again, from the Wiki:

Demetrius found himself unable to return to the battlefield because of the deployment of 300 elephants in his path. The ancient sources repeatedly emphasise the effect of elephants on horses, which are alarmed by the smell and noise of elephants and are loath to approach them. Demetrius would not have been able to take his horses through the line of elephants, nor manoeuvre around such a large quantity of elephants. This 'elephant manoeuvre' was the decisive moment in the battle, but it is not clear how it came about; Plutarch only says that "the [allied] elephants were thrown in his way". If the elephants had indeed been held in reserve, then it might have been relatively straightforward to deploy them, but as discussed, it is not clear why so many elephants would have been held in reserve. However, it is also possible that the deployment of the elephants was a piece of improvisation during the battle, though moving such a large number of elephants in such a coordinated manoeuvre in the middle of the battle would have been difficult. Since he was the only allied commander with significant experience of handling elephants, it has been assumed that Seleucus was responsible for this manoeuvre.

BONUS LINK:

List of battles involving war elephants (Wikipedia)

Overall, I tend to concur with your estimate that the elephants usually proved to be more of a liability than an asset. However, they did have some successes. Two examples are: the Battle of Ipsus which was decided by a judicious deployment of an elephant reserve and the "Elephant Battle" in which Antiochus I routed the Galatians - I couldn't find a full-length description of it now on the web, but it's mentioned here.

An archaeology book somewhat unexpectedly has a very nice overview on elephant warfare in antiquity.

Both of the following accounts are from Polybius.

At the Battle of Tunis, Xanthippus used his elephants to charge the Roman line. While some of the Romans avoided the elephants to charge the Carthaginian right and the formation held due to its depth, those at the front were trampled. The Romans were later flanked by cavalry and the elephants also accounted for the bulk of the casualties from then on.

During the period before the Second Punic War when Carthage was consolidating power in Spain, Hannibal defeated a combined force of the Carpetani and other neighbouring tribes in a battle in which the majority of the killing was done by elephants. However, the Carpetani had to cross a river to attack the Carthaginians, so it's quite possible that the battle could have ended the same way without the elephants.