misc edits, stub for 'diagonal' function
misc edits
misc refactoring and documentation