3 ms·

I’ve never used Racket, but reading your description of the documentation (and Scribble) makes me want to check out that aspect of it. I wonder how it compares

by db48x 4y ago

I’ve never used Racket, but reading your description of the documentation (and Scribble) makes me want to check out that aspect of it. I wonder how it compares with rustdoc? I do mostly Rust these days and its generated documentation is usually really good.

djhaskin987 4y ago
The only other equal I've seen to scribble around is Python's Sphinx. I use Sphinx for all my projects no matter what language they're in because it's so good.
db48x 4y ago
Oh, I see. Scribble looks a little like TeX, but actually it’s an alternate read syntax/dsl. The first example where they show off the real utility of it is: @tabular[#:sep @hspace[1] (list (list @bold{Animal} @bold{Food}) (list "mouse" "cookie") (list "moose" "muffin"))] which really drops it in your lap. “tabular” isn’t from some fixed list of keywords, it is an ordinary racket function that you can call, with ordinary arguments that can be strings, lists, etc. Presumably there will be an example in the next page or two with @define[…] in it to close the loop. And the table of contents promises literate programming as well. Someone was really thinking when they put this together; I really like it. The documentation generated for individual functions (such as <https://docs.racket-lang.org/scribble/base.html#(def._((lib._scribble%2Fbase..rkt)._italic)) https://docs.racket-lang.org/scribble/base.html#(def._((lib....>) is fairly nice as well. Readable, linked together by hyperlinks on the type predicates as well as hyperlinks in the body of the documentation itself; it’s pretty good. Rustdoc puts links to the source code for each one though, and I would soon miss that.
- lispm 4y ago
  See Scribe from the end 70s: https://en.wikipedia.org/wiki/Scribe_(markup_language) https://en.wikipedia.org/wiki/Scribe_(markup_language)
  - db48x 4y ago
    Good point; it looks like Scribe even more than TeX.
sph 4y ago
The generated Rust docs... are not very good. And on more complex types you have a ton of traits, with methods and all their lifetimes and generic parameters which are really hard to follow if you're unfamiliar with a library or Rust in general. Also, even the biggest libraries (clap for example) reserve a couple paragraphs for the front page prose and leave the type docs to speak for themselves... which is just not good enough. I would go as far as to say that a non-negligible part of why people are intimidated by Rust is the rustdoc format and layout. Thankfully it makes up for it with an incredible Rust Book. To me the gold standard of docs is Elixir followed by Racket. Even Go's docs are better than Rust, but that's mostly because of a much simpler type system, so simpler autogenerated docs for structs and their methods.
- db48x 4y ago
  I really got annoyed by the Go package docs after I programmed in Go regularly for about a year. They were just so artless and flat. Each one is just a big list of all the stuff in the package, with no indication that the code has any structure to it at all. It was a few years ago though; perhaps it has gotten better? Scribble beats rustdoc hands–down when it comes to authoring documentation, but even with Rustdoc you can do a good job of it if you try (http://db48x.net/reposurgeon/rust-port-docs/reposurgeon/pathmap/index.html http://db48x.net/reposurgeon/rust-port-docs/reposurgeon/path...). I’ll have to check out Elixir next.
  - sph 4y ago
    Go docs are pretty terse and lifeless, agreed. Here's an example of Elixir docs: https://hexdocs.pm/ecto/Ecto.html https://hexdocs.pm/ecto/Ecto.html Note the layout, the amount of prose to introduce a module and the function documentation that is not limited to just a quick line but often has multiple examples and tries quite hard to be clear and extensive. There is no reason Rust docs couldn't be that good, but the example has to come from the top: improve the std docs, and everything will follow suit.
    - cultofmetatron 4y ago
      ecto and phoenix are shining examples of well written docs but its hardly the standard for elixir as a whole. many of the docs for most libraries are just lists of functions. some might have a short description though you're usually relying on a dialyzer definition at best.

by db48x 4y ago

djhaskin987 4y ago

The only other equal I've seen to scribble around is Python's Sphinx. I use Sphinx for all my projects no matter what language they're in because it's so good.

db48x 4y ago

Oh, I see. Scribble looks a little like TeX, but actually it’s an alternate read syntax/dsl. The first example where they show off the real utility of it is: @tabular[#:sep @hspace[1] (list (list @bold{Animal} @bold{Food}) (list "mouse" "cookie") (list "moose" "muffin"))] which really drops it in your lap. “tabular” isn’t from some fixed list of keywords, it is an ordinary racket function that you can call, with ordinary arguments that can be strings, lists, etc. Presumably there will be an example in the next page or two with @define[…] in it to close the loop. And the table of contents promises literate programming as well. Someone was really thinking when they put this together; I really like it. The documentation generated for individual functions (such as <https://docs.racket-lang.org/scribble/base.html#(def._((lib._scribble%2Fbase..rkt)._italic)) https://docs.racket-lang.org/scribble/base.html#(def._((lib....>) is fairly nice as well. Readable, linked together by hyperlinks on the type predicates as well as hyperlinks in the body of the documentation itself; it’s pretty good. Rustdoc puts links to the source code for each one though, and I would soon miss that.

lispm 4y ago
See Scribe from the end 70s: https://en.wikipedia.org/wiki/Scribe_(markup_language) https://en.wikipedia.org/wiki/Scribe_(markup_language)
- db48x 4y ago
  Good point; it looks like Scribe even more than TeX.

sph 4y ago

The generated Rust docs... are not very good. And on more complex types you have a ton of traits, with methods and all their lifetimes and generic parameters which are really hard to follow if you're unfamiliar with a library or Rust in general. Also, even the biggest libraries (clap for example) reserve a couple paragraphs for the front page prose and leave the type docs to speak for themselves... which is just not good enough. I would go as far as to say that a non-negligible part of why people are intimidated by Rust is the rustdoc format and layout. Thankfully it makes up for it with an incredible Rust Book. To me the gold standard of docs is Elixir followed by Racket. Even Go's docs are better than Rust, but that's mostly because of a much simpler type system, so simpler autogenerated docs for structs and their methods.

db48x 4y ago
I really got annoyed by the Go package docs after I programmed in Go regularly for about a year. They were just so artless and flat. Each one is just a big list of all the stuff in the package, with no indication that the code has any structure to it at all. It was a few years ago though; perhaps it has gotten better? Scribble beats rustdoc hands–down when it comes to authoring documentation, but even with Rustdoc you can do a good job of it if you try (http://db48x.net/reposurgeon/rust-port-docs/reposurgeon/pathmap/index.html http://db48x.net/reposurgeon/rust-port-docs/reposurgeon/path...). I’ll have to check out Elixir next.
- sph 4y ago
  Go docs are pretty terse and lifeless, agreed. Here's an example of Elixir docs: https://hexdocs.pm/ecto/Ecto.html https://hexdocs.pm/ecto/Ecto.html Note the layout, the amount of prose to introduce a module and the function documentation that is not limited to just a quick line but often has multiple examples and tries quite hard to be clear and extensive. There is no reason Rust docs couldn't be that good, but the example has to come from the top: improve the std docs, and everything will follow suit.
  - cultofmetatron 4y ago
    ecto and phoenix are shining examples of well written docs but its hardly the standard for elixir as a whole. many of the docs for most libraries are just lists of functions. some might have a short description though you're usually relying on a dialyzer definition at best.