OMERO Developer doc tidying (rebased onto develop)



This is the same as gh-820 but rebased onto develop.

----

Addressing a multitude of minor issues and general formatting.

More to come on other PRs, trying to keep each one to a reasonably reviewable chunk!

                    
I know this isn't part of this PR so please ignore for now, but should the heading really be 'Decorators' rather than '@Decorators'?