add commentary to container reconciler code

[Alistair Coles]

The container reconciler process and code is potentially confusing to someone not familiar with the code. In particular, container db object tables are used to maintain queues of potentially misplaced objects, and the table columns are re-purposed e.g. 'etag' actually stores a timestamp, content-type stores an action command.

It would be kind to future maintainers to add some commentary in the code:

- an overview of what is happening at a high level

- highlight that where db row entries are assigned apparently incorrect values, that in fact it is not a bug

- explain some of the logic e.g. when and why tombstones are thrown

The code is mainly in swift/container/replicator.py and swift/container/reconciler.py

There is some discussion in the storage policies overview doc. I'm suggesting adding code comments, not docs.

[Mohit Motiani (mohit-motiani)]

I can see most of the methods contains commentary. Do you want it in all the methods?

[Thiago da Silva (thiagodasilva)]

I think Alistair's idea is not really documentation as much as add comments in certain areas to explain reasoning. Using the same example he mentioned, there's documentation for the method throw_tombstones, but it doesn't really explain why we do that in the reconciler.