Until `external_traits` is cleaned up (i.e., no longer behind a
`RefCell`), `DocVisitor` will have to `take` `external_traits` -- just
like `DocFolder` -- to prevent `RefCell` runtime errors.
`DocFolder` allows transforming the docs, accomplished by making its
methods take and return types by-value. However, several of the rustdoc
`DocFolder` impls only *visit* the docs; they don't change anything.
Passing around types by-value is thus unnecessary, confusing, and
potentially inefficient for those impls.
`DocVisitor` is very similar to `DocFolder`, except that its methods
take shared references and return nothing (i.e., the unit type). This
should both be more efficient and make the code clearer.
There is an additional reason to add `DocVisitor`, too. As part of my
cleanup of `external_traits`, I'm planning to add a `fn cache(&mut self)
-> &mut Cache` method to `DocFolder` so that `external_traits` can be
retrieved explicitly from the `Cache`, rather than implicitly via
`Crate.external_traits` (which is an `Rc<RefCell<...>>`). However, some
of the `DocFolder` impls that could be turned into `DocVisitor` impls
only have a shared reference to the `Cache`, because they are used
during rendering. (They have to access the `Cache` via
`html::render::Context.shared.cache`, which involves an `Rc`.)
Since `DocVisitor` does not mutate any of the types it's visiting, its
equivalent `cache()` method will only need a shared reference to the
`Cache`, avoiding the problem described above.
