Improve API documentation

[Bagoult]

Hello! I improved the documentation of the REST-API to make it easier for future users. Here is what it does:

• Refreshes outdated information (deleted field is now a boolean, share_api#add endpoint was changed recently).
• Completes sections about payloads, and creates separate sections to give example of possible return values. (This way, the reader knows which fields appear in the return value, but shouldn't appear in the payload.)
• Explains a few things that I found confusing the first time I came across them (ex: sending "expire": 0 doesn't remove the current expiration date, but sets it to 0).
• Another curl example to show how to create a new poll.

[dartcafe]

Awesome. Great work. Unfortunately the structures are still subject of changing. Especially the update poll method needs some more work, since I plan to change the structure and differentiate between read only properties and properties wich can be changed.

[dartcafe]

And, it would be good if you could sign your commits.

[dartcafe]

Give me a hint, when you are finished. And thanks a lot, there were really a lot of missing things and broken docs.

[dartcafe]

Great so far.

[Bagoult]

Everything should be signed off now and ready to merge @dartcafe :)

[dartcafe]

@Bagoult Ah. And a rebase is not really necessary until you don't need the current target branch for testing your build.

[github-actions]

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!