[KV] This documentation stinks about cloudflare-docs HOT 3 OPEN

A bit blunt but some fair points, we really ought to be generating API reference docs more systematically, starting from our TypeScript types, probably even generated from doc comments in those types (so that vscode tooltips can also show the same docs, etc.).

Of course you still need human judgment to decide what details need to be covered in the description (e.g. "does delete throw an exception if the key doesn't exist?") but with more auto-generated docs it'll be easier to get the core developers to take ownership of such content, whereas today the reference docs tend to be owned by the same people that write the overview docs and design the overall organization of the site. I think core developers are the best people to write API reference docs, but often not the best people to write overviews.

from cloudflare-docs.

Quick note on the API reference docs - those live here: https://developers.cloudflare.com/api and are generated from our schemas. We're also working with our internal teams to help improve the API reference descriptions that get written so they're easy to read and understandable.

I know it doesn't solve all of your problems, and it sucks that the reference docs aren't where you may've expected to find them. The docs team is working to bring a tighter integration between our long-form content and the API reference so this experience gets better.

from cloudflare-docs.

@crwaters16 This user is complaining specifically about the Workers JavaScript runtime APIs, not the Cloudflare control plain REST API. The Workers runtime APIs unfortunately do not have auto-generated documentation today.

from cloudflare-docs.