need better developer documentation

[aspiers]

This codebase has gotten significantly more complex in the last ~12 months, due to the addition of several new source services. That doesn't have to be a bad thing, but currently there's a lot of code I don't understand, and if that's true for me as one of the maintainers then surely the problem must also exist for new contributors, and probably for users to some extent too.

I think we can fix this fairly easily in a two-pronged attack:

• write a document which describes the overall architecture and how all the classes fit together
• add docstrings to all the important classes explaining at a high-level what they do.

Of course it would also be nice if every method had a docstring, but I don't think that's as important, since if it's clear what a class is supposed to do, then it's already a lot easier to figure out what individual methods are doing just by reading the code.

I already gave one example of the kind of confusion this approach would address: if the TarSCM.scm.tar class had a docstring explaining what it does, then it would become clear whether it is a genuine problem that it is deriving from TarSCM.scm.base even though tar is not a real SCM. We could then decide whether the latter needs a rename or whether the current class design needs changing.

@M0ses @adrianschroeter Does this all make sense to you, and would you be able to help me put this together? I think we could probably capture a lot of the most important info in a Jangouts session (1 hour should be enough). Then it should not be too hard to write the docs describing what we captured.