Better way to document actual code...

[PDoakORNL]

It is apparent when reading the developing section of the manual that the documentation of specific classes is mostly out of date and/or misleading wrt the actual code.

Describe the solution you'd like

The explanatory part of this documentation actually belongs in the source, I think it would do more good and be easier to keep current there. Doxygen can actually support pretty equivalent markup to the rst the docs are in now. The existing in source documentation is certainly more up to date anyway. I think more of the future deprecation or improvement plans in the source would help as well. I think those actually are more likely to be read.

The overall batched design could be described and updated with information from ECP documents where applicable and be less explanatory. (This is easy to say harder to do.). This should provide something of an outline into the doxygen docs. I believe hyperlinking is even possible.

Unfortunately our doxygen is really terrible to look at and navigate above the single class level, I'd like to think we can do something about that.

Describe alternatives you've considered
I've added to and still am adding what we have and thinking about trying to keep it synchronized and even remembering its there is hard.

Additional context
I'd really like contributors to understand more about how they're expected to write code and what code they should be interfacing with before PR review.