chore: move docs from markdown files to rust source

[mladedav]

Closes #929

Motivation

Documentation created with include_str does not show in rust-analyzer tooltips. The issue is tracked by rust-analyzer but there's no indication anyone would be able to work on it anytime soon.

Solution

Move the documentation inline. handlers_intro.md and debugging_handler_type_errors.md were used in two places so there is some duplication but not too much, one is 7 and the other 40 lines including empty lines.

Interestingly, even clippy and rustdoc seems to not support include_str fully as they do not warn on included docs the same way as they do on inline docs.

[jplatte]

Thanks for taking care of this. I'll try to review in the next couple days.

[yanns]

What is the best way to review this? Generating doc locally and comparing with the current version?

[jplatte]

That's a good question 😅

… there are some git diff settings for highlighting moved code, and for ignoring whitespace. That's probably what I would have tried.

[jplatte]

We may have waited long enough w/ finishing this that it won't be necessary anymore.. 😅

rust-lang/rust-analyzer#21303

[mladedav]

If it's fixed in rust analyzer and we close this, that's still the best case scenario I'd say.

[joshka]

We may have waited long enough w/ finishing this that it won't be necessary anymore.. 😅

It's still IMHO nicer to read it as code than in a hover pane. I would advocate for accepting this over closing it even with the r-a change.

To review that the docs are the same, perhaps use cargo doc --output-format json and compare before and after? Hopefully the identifiers would end up the same (if not then the comparison would have to use a tool - perhaps there's something that does this already against the json?)