documentation: improve readability; line length, indentation, highlighti...

...ng.

related pull requests: #1036 #1038 #1043