On 25.06.2014 20:22, John Scipione wrote:
On Wed, Jun 25, 2014 at 2:07 PM, Ingo Weinhold <ingo_weinhold@xxxxxx> wrote:Why indent with spaces? Unless we have a style guide for documentation I'm not aware of, I would simply apply the coding style guide and indent with an additional tab level.I don't really care too much either way, but, indenting with spaces makes the docs line up nicely and read easier.
Either is debatable. Since the different leading keywords (\param, \returns, \retval) have different length, the indentation varies, which looks rather untidy IMO. And I can't say that I find the tab indented text less easy to read. In fact the lines with the leading keywords separate the blocks more distinctly, since they are longer than four characters.
Indenting docs like code seems pretty silly because it's not code.
That isn't an argument, though. There are coding styles that indent function arguments to the opening parenthesis. That certainly looks nicer and is easier to read. However, it also wastes space and is less convenient to navigate and edit.
I even think that maybe breaking on 80 columns is silly, we should just turn word-wrap on and write docs free-form.
The soft-wrapped lines won't be indented at all and things will really get harder to read.
CU, Ingo
