How prevalent are siddhis in buddhism? Abilities (such as flying through the air, walking through solid obstructions, diving into the ground, walking on water, and so forth) are performed by changing one element, such as earth, into another element, such as air.

How does one expect to achieve them?

I have read some commentaries which claim they are mere illusions on the path to enlightenment and that the true sadhka shouldn't be distracted by them and should aim for higher realms.

Moreover are these claims made in documentaries true?
Siddhi - a paranormal power possessed by a siddha – is a true phenomenon. These are certain by-products of the practice itself. But just as gain, respect and fame can become obstacles to liberation, so, too, can such siddhi. Such phenomena are categorized under the Tenth Army of Mara. A battle faced by meditation masters, this last army is perhaps the most lethal of all. In the Buddha's time there was even a man, Devadatta, who tried to kill the Buddha under its influence.

There was once a layman who told that the Buddha should widely deploy all of his disciples who had psychic powers and ask them to demonstrate miracles to the people. "People will be really impressed," the layman said. "You'll get a lot of followers that way. The Buddha refused. Three times the request was repeated, and three times it was refused. Finally the Buddha said, "Layman, there are three types of psychic powers. One is the power to fly in the air and dive into the earth, and to perform other superhuman feats. The second is the power to read other people's minds. But there is a third psychic power, the power of instruction. This last power is the most important psychic power. The first two psychic powers can be attained and displayed if this interests you. It is not essential, or a hindrance, if you know it for what it is. 

True disciples of the Buddha are more interested in developing ‘the Four Irdhi-paada.’ Iddhiya: of attaining completion or perfection; pado: root or basis -the root or basis of attaining completion or perfection. Hence it is called iddhipada. There are four kinds of iddhipada. But this is another subject/answer for another time/question.