gpio: Documentation update

Update a slew of documentation files with the latest changes in the
API/ABI. Again stress that sysfs is deprecated. Add all new flags and
clean up and move some text.

Signed-off-by: Linus Walleij <linus.walleij@linaro.org>