Docs are confusing - suggestion for improvement of first paragraph

[PhilipDaniels]

This opening paragraph

Since this is a tool for helping the developer of a library or application write better code, it is recommended not to include Clippy as a hard dependency. Options include using it as an optional dependency, as a cargo subcommand, or as an included feature during build. All of these options are detailed below.

could be much better written. First, get rid of the passive voice "Since this is..." and say "Clippy is..."

Secondly, please say how Clippy is implemented (a compiler plug in, a binary, or something else) and explain how it fits into the development cycle. At the moment it jumps straight in to advising "do not include as a hard dependency" which is very confusing. As a new user, I am thinking "why on earth is a lint tool a dependency anyway?"

I should say I opened this issue because I didn't understand why running cargo clippy twice in succession did not redisplay the warnings. Noted on #1495. As a tool user, I want to have a clear mental model of how it works.

[Manishearth]

This is all under churn right now, I don't think it's worth explaining the current model given that we're soon moving to a better one.

[Manishearth]

Since you seem interested, the current model is that clippy is a compiler plugin, but there's this complicated tangle where cargo-clippy pretends to be cargo and then pretends to be rustc with the plugin preloaded due to how compiler plugins work. This is suboptimal.

The reason we recommend against using it as a hard dependency is because that's actually how plugins are loaded in general and folks would do this a lot in the past, but we want them to move to cargo-clippy.