[haiku-commits] Re: haiku: hrev47422 - docs/user/support headers/os/support src/kits/support
- From: John Scipione <jscipione@xxxxxxxxx>
- To: "haiku-commits@xxxxxxxxxxxxx" <haiku-commits@xxxxxxxxxxxxx>
- Date: Wed, 25 Jun 2014 15:12:56 -0400
On Wed, Jun 25, 2014 at 2:53 PM, Ingo Weinhold <ingo_weinhold@xxxxxx> wrote:
> 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.
> 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.
Sure but you tend to have several of the same type of keyword in a
row, several \param's, and several \retval's so the lines in each
group line up nicely. It's also a happy coincidence that \return is
the same length as \retval. Tab-indented text is harder to read.
because items do not line up and you get 2 indent levels where there
should be 1. That's not how I'd line up a bunch of bullet points in a
document because it would look ugly and readability would suffer, it's
the same thing here.
>> Indenting docs like
>> code seems pretty silly because it's not code.
> That isn't an argument, though.
It's an argument in that applying the same guidelines used for code on
docs would not necessarily produce nice results. What I'm saying is
that if we need guidelines for docs we need /different/ guidelines
then we use for code.
> 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.
The difference here is that the function name changes and then you
have to re-indent all the parameters so that everything continues to
line up. \param or \return is not going to change. Also function names
can be very long which means you have to do a lot of indenting while
doxygen keywords are short.
>> 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.
True, but, you change one word in a long paragraph and you may have to
re-wrap a dozen lines manually, very annoying (and not something you
run into in code). Soft-wrapping would make things less readable but
would make the docs easier to change.
Other related posts:
