Barrier API documentation is not informative

What should we add?

A Google search for “qiskit barrier” leads one to its entry in the API reference as the first hit. Unfortunately, this page contains only a circular definition, and does not even explain what a barrier does:

Barrier instruction.

Create new barrier instruction.

There is a much more useful description by @chriseclectic on StackExchange, with tens of upvotes. I believe a similar explanation should be incorporated into the Barrier docstring(s).

[jakelishman]

For reference, this is Chris’s answer on stackexchange. The relevant docstrings that need updating are the QuantumCircuit.barrier method and the Barrier class.

[HuangJunye]

@faraimazh Do you want to work on this issue? I can assign you.