4 ms·

I'm mostly comparing this: http://flask.pocoo.org/docs/1.0/api/#api http://flask.pocoo.org/docs/1.0/api/#api to this: https://golang.org/pkg/net/http/ https:

I'm mostly comparing this: http://flask.pocoo.org/docs/1.0/api/#api http://flask.pocoo.org/docs/1.0/api/#api to this: https://golang.org/pkg/net/http/ https://golang.org/pkg/net/http/ If the source weren't hyperlinked, I'd be lost on the latter. edit: I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.

weberc2 8y ago
First of all, https://godoc.org/net/http https://godoc.org/net/http is the page to visit; it serves documentation for all public packages, not just the standard library, and it's generally a little nicer. That everything is on the same site is a big deal because maintainers don't have to link to their dependencies and readers don't have to deal with the inconsistent presentation of documentation across the ecosystem. The distinction I see is that someone put a lot more care into Flask's documentation (including the theme, which is actually a little hard to read since it renders certain things in small italic font), which is great but not indicative of the broader ecosystem. The most significant distinction wrt readability is that the Go page has types for _every_ parameter with links to the type definition. For all of the care put into the Flask doc, you still see things like this all over: > view_func – the function to call when serving a request to the provided endpoint I have no idea what the signature of that callback is. Meanwhile Go has https://godoc.org/net/http#HandleFunc https://godoc.org/net/http#HandleFunc which clearly shows the type for the handler callback (with links to types): func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) > I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code. I tried to use Racket (it looks really neat), but I just spent so much time trying to figure out what to pass into each function. It was nearly impossible since types are often absent. That's just not how I want to spend my free time. :(
- jstewartmobile 8y ago
  That sounds like a stronger defense of types than Go's documentation.
  - weberc2 8y ago
    It largely is. Formalized types allow a documentation tool to do a lot of heavy lifting. But Go's documentation system is still quite a lot nicer than javadoc, doxygen, etc. for other statically typed languages.

weberc2 8y ago

First of all, https://godoc.org/net/http https://godoc.org/net/http is the page to visit; it serves documentation for all public packages, not just the standard library, and it's generally a little nicer. That everything is on the same site is a big deal because maintainers don't have to link to their dependencies and readers don't have to deal with the inconsistent presentation of documentation across the ecosystem. The distinction I see is that someone put a lot more care into Flask's documentation (including the theme, which is actually a little hard to read since it renders certain things in small italic font), which is great but not indicative of the broader ecosystem. The most significant distinction wrt readability is that the Go page has types for _every_ parameter with links to the type definition. For all of the care put into the Flask doc, you still see things like this all over: > view_func – the function to call when serving a request to the provided endpoint I have no idea what the signature of that callback is. Meanwhile Go has https://godoc.org/net/http#HandleFunc https://godoc.org/net/http#HandleFunc which clearly shows the type for the handler callback (with links to types): func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) > I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code. I tried to use Racket (it looks really neat), but I just spent so much time trying to figure out what to pass into each function. It was nearly impossible since types are often absent. That's just not how I want to spend my free time. :(

jstewartmobile 8y ago
That sounds like a stronger defense of types than Go's documentation.
- weberc2 8y ago
  It largely is. Formalized types allow a documentation tool to do a lot of heavy lifting. But Go's documentation system is still quite a lot nicer than javadoc, doxygen, etc. for other statically typed languages.