I have been learning and writing in Rust since 2018 (though not commercially). I earn by writing Ruby.
So, unfortunately I observe the same trend in Rust like in Ruby.
In Ruby (I don't why 
) the majority prefer to use language features like metaprogramming, at least 5 level inheritance, inventing their own DSL (on almost every occasion) which results in over-engineered solutions and difficult to read and understand code-base (with no documentation!).
In Rust I observe that as soon as someone comes up with and idea and creates a crate, he/she starts to further pack it with features and macros (as if it is a MUST!!!).
Usually no documentation and examples are provided or the "docs" are very poor and is usually not helpful.
For example, I'd be happy to see well documented modules and traits rather than a couple of ugly macros.
I am not claiming "No macros at all", but it seems that the community is overly passionate with creating macros on every occasion and over use it. Sometimes I wish macros would not exist at all in Rust. This must be addressed.
I have been writing Rust for a couple of years, and my experience has been mostly the opposite of what you described.
I find the documentation in Rust's ecosystem the best among all the languages that I have used in my career, and whenever I see the use of a macro I've found it justifiable.
It's not just about creating DSLs for the sake of it. Macros such as json! from serde_json really improve the DX, yes, at the expense of making it harder for IDEs to gain insights of what's going on within them.
All of the crates that I use are open source, and if something that was implemented as a macro can be better represented with the use of other abstractions such as traits, there's nothing stopping the users of such crate from creating a PR to do the aforementioned improvement.
Well, let me give you an example. Please follow this link (clap crate) and try to visit other "chapters" (1,2...) and see what you'll get. All links are broken. While I have nothing against this crate, I just want to point out what I mean. It is just one example among hundreds such crates.
Are you using IntelliJ IDEA ?
With the exception of web_sys , I've found that IntelliJ autocomplete / jump-to-def works so damn well that I rarely go to docs (except for examples).
Having an IDE that indexes all the types (vs, say, notepad), makes a huge difference in navigating libraries.
That's just a bug on the sidenav navigation. I'm on the smartphone and managed to go to chapter 1 and then chapter 2 by clicking on the links at the bottom of the page.
This means that this has nothing to do with the crate in question.
Please provide specific examples. You must be using not very well-designed crates, because macros are (rightfully) regarded as a sort of last-resort solution in most cases by the community. If something can be expressed in a typed way with generics and traits, it shouldn't be a macro.
One exception is derive macros, where the syntactic structure of the type definition is necessary and sufficient to automatically create impls, so a macro is the right solution.
Two things:
- I cannot reproduce this at all. I have visited chapters 1, 2, and 3 without any problem.
- In what way would a documentation bug even relate to macros being overused? I don't see any connection. Macros can be documented just like functions or traits. People who don't document their macros won't document their generic types and traits, either.
It's a bug in the integration between Rustdoc and docs.rs. The problem affects the sidebar, not the main module pages. It's been fixed, but the docs for that crate haven't been rebuilt:
It has nothing to do with macros. clap is just a crate with docs that nudge you towards using lateral navigation, so people noticed it on there first.