doc: document the reasons for deprecating interfaces
doc: document the reasons for deprecating interfaces

Use the @deprecated doxygen tag to mark deprecated functions and explain
why their usage is discouraged.

Signed-off-by: Bartosz Golaszewski <e5d45fddd9040473413b909b802f629a971ad04c@baylibre.com>

brgl/libgpiod,brgl/libgpiod,brgl/libgpiod,brgl/libgpiod