Cleaning up documentation

[nyurik]

Applied this lint:

just 'clippy-flags=-W clippy::doc-markdown' clippy-fix

I also had to search/replace:

[`to_decimal`()]  ->  [`to_decimal()`]

I have never seen parenthesis used as part of the link, so this is perhaps why clippy handles it like that.

There are still a few warnings being produced, but they have to do with how some of the links are constructed, e.g. this link

[File::index_names().len()][File::index_names()]

shows a warning

you should put bare URLs between </> or make a proper Markdown link

Not certain how these should be fixed, but there are 10-20 of such warnings. What are you linking to here?

[Byron]

Incredible, I wasn't aware of all the tricks clippy has up its sleeves, and appreciate all the improvements that are made by it (and the industrious human who controls all that, thank you :)).

I managed to find a couple of other issues around these function(<ellipsis>) doc strings, and am happy about these massive improvements.

[nyurik]

thx @Byron ! Do you actually want to include parens everywhere in the docs? I haven't seen many usages like that. Most of the time I see either [Some::Path::to_function] or the Markdown style links like [...text...](...link...). In both cases they tend to be wrapped in backticks

[Byron]

The reason I do this is that I'd like to differentiate between fields and methods. Admittedly, most of the time the name takes care of that, but I felt like not taking chances.

If the current style disturbs tooling too much, I think that's enough to remove (…) and () in links even though I'd love to have it styled so that their nature is clear.