3 ms·

As a crate author a thing I don’t like is that rustdocs are not easily sharable even though the same code might be used in a function, module and readme doc. I

As a crate author a thing I don’t like is that rustdocs are not easily sharable even though the same code might be used in a function, module and readme doc. I took a stab at a JINJA based rustdoc templating solution: https://docs.rs/drydoc/latest/drydoc/ https://docs.rs/drydoc/latest/drydoc/. It’s not “done” but I think the idea holds promise. Anything else like this that you’ve seen? My other option is to use include_str macro.

airstrike 1y ago
Thanks for sharing and good luck on your project. I think better docs is a worthwhile idea overall and although the implementation details may vary, a template solution could appeal to some people. Separately, I find it disheartening that people come into this thread with some bone to pick against Rust and just downvote everything they see without adding anything to the conversation. Part of me feels that a downvote should require a reply for this reason.
- flysand7 1y ago
  There's no downvote button for me, I had no idea HN had downvotes
  - schneems 1y ago
    FWIW I’ve got one. You need over 1k karma I think (or maybe it is based on some other metric). A post with more downvotes than upvotes will show up as grey for me too.
    - LtdJorge 1y ago
      The grey part is for everyone. Flagged posts show an even lighter grey, IIRC.
- schneems 1y ago
  Thanks! I’m less soliciting for people to use this specific solution and almost sharing aloud hoping someone will say “duh use crate X” Thanks for the concern over votes. I think your comment turned the tides, I’m at +1 now. Overall Rust has the best doc eco system of any lang I’ve used. I wish more communities stole from rust. The most useful part of any doc is an example and rustdoc makes it really easy to write one and keep it from doc-rotting. My particular pain is for an author who aims to go above and beyond. Specifically I was thinking of the winnow tutorial when writing this crate. The return type example is straight from what I would like to be able to toggle on/off in their docs. I also have a more mature library for easing maintenance burdens for tutorial writing but it’s not rust https://github.com/zombocom/rundoc https://github.com/zombocom/rundoc

airstrike 1y ago

Thanks for sharing and good luck on your project. I think better docs is a worthwhile idea overall and although the implementation details may vary, a template solution could appeal to some people. Separately, I find it disheartening that people come into this thread with some bone to pick against Rust and just downvote everything they see without adding anything to the conversation. Part of me feels that a downvote should require a reply for this reason.

flysand7 1y ago
There's no downvote button for me, I had no idea HN had downvotes
- schneems 1y ago
  FWIW I’ve got one. You need over 1k karma I think (or maybe it is based on some other metric). A post with more downvotes than upvotes will show up as grey for me too.
  - LtdJorge 1y ago
    The grey part is for everyone. Flagged posts show an even lighter grey, IIRC.
schneems 1y ago
Thanks! I’m less soliciting for people to use this specific solution and almost sharing aloud hoping someone will say “duh use crate X” Thanks for the concern over votes. I think your comment turned the tides, I’m at +1 now. Overall Rust has the best doc eco system of any lang I’ve used. I wish more communities stole from rust. The most useful part of any doc is an example and rustdoc makes it really easy to write one and keep it from doc-rotting. My particular pain is for an author who aims to go above and beyond. Specifically I was thinking of the winnow tutorial when writing this crate. The return type example is straight from what I would like to be able to toggle on/off in their docs. I also have a more mature library for easing maintenance burdens for tutorial writing but it’s not rust https://github.com/zombocom/rundoc https://github.com/zombocom/rundoc