35 ms·

A lot of the docs don’t explain what a module does - for example: > dns.providers.azure wraps the provider implementation as a Caddy module. Well great what d

by jarym 4y ago

A lot of the docs don’t explain what a module does - for example: > dns.providers.azure wraps the provider implementation as a Caddy module. Well great what does the provider implementation do? It’s the same for all DNS and not so useful if I’m coming from Apache or Nginx. At least explain what I’ll be able to do with this module. From http.handlers.push: > http.handlers.push is a middleware for manipulating the request body. That’s a bit generic - any examples? There’s a lot of ways to modify the request body so what can I do with this? There are 2 http.authentication.providers.jwt - both unofficial and both with 0 documentation. There has to be some standards here, why link to blank docs from your site? All-in-all it just feels meh. I like to read docs that’ll give me the technical ins and outs of every function with some examples ideally. Microsoft does a decent job of this as does Postgres (and others but these two come to mind immediately). Envoy is pretty nice here too and Nginx close.

francislavoie 4y ago
Re "dns.providers.azure", that's a third-party module, we don't maintain that. The documentation you see in the JSON docs is auto-generated from code comments (godoc) so it's the maintainer's responsibility to write good comments that can act as documentation. Re "http.handlers.push", fair point, that one's lacking/misleading. But this is a feature that was just added to satisfy a specific need, then fell by the wayside. Mostly because now Chrome is removing support for Server Push, so we'll need to deprecate this feature, in favor of HTTP 103 Early Hints which is the effective replacement for it. Also, in general, we tend to spend more effort on maintaining the Caddyfile docs than the JSON docs, because the large majority of users use the Caddyfile. See https://caddyserver.com/docs/caddyfile/directives/push https://caddyserver.com/docs/caddyfile/directives/push for the push handler, complete with examples. Re "http.authentication.providers.jwt", well again, I think that's an issue with the module's maintainer not sufficiently using godoc comments. The maintainer registered the module under two different module paths (renamed repo) so it caused a duplicate. We'll need to manually remove the duplicate from the database, I think. It might be because there's conflicting ones that no docs are shown (cause the backend which serves the API docs is confused, I dunno, it's a bug clearly, will need to dig deeper).

by jarym 4y ago

francislavoie 4y ago

Re "dns.providers.azure", that's a third-party module, we don't maintain that. The documentation you see in the JSON docs is auto-generated from code comments (godoc) so it's the maintainer's responsibility to write good comments that can act as documentation. Re "http.handlers.push", fair point, that one's lacking/misleading. But this is a feature that was just added to satisfy a specific need, then fell by the wayside. Mostly because now Chrome is removing support for Server Push, so we'll need to deprecate this feature, in favor of HTTP 103 Early Hints which is the effective replacement for it. Also, in general, we tend to spend more effort on maintaining the Caddyfile docs than the JSON docs, because the large majority of users use the Caddyfile. See https://caddyserver.com/docs/caddyfile/directives/push https://caddyserver.com/docs/caddyfile/directives/push for the push handler, complete with examples. Re "http.authentication.providers.jwt", well again, I think that's an issue with the module's maintainer not sufficiently using godoc comments. The maintainer registered the module under two different module paths (renamed repo) so it caused a duplicate. We'll need to manually remove the duplicate from the database, I think. It might be because there's conflicting ones that no docs are shown (cause the backend which serves the API docs is confused, I dunno, it's a bug clearly, will need to dig deeper).