Adjust section for ddoc comments in style guide.

[jmdavis]

Some changes per the discussion in #2129

Phobos uses both /++ +/ and /** */ heavily, and there are cases where /++ +/ works better than /** */, because the documentation includes /* */ comment. Andrei agreed that both are acceptable. I did add a note about ditto comments, since those should be just fine as single line comments.

Also, I removed the bit about not having indentation in comments, since I'm pretty sure that most existing ddoc comments in Phobos do have indentation, and I don't see any reason not to have it. Personally, I think that it's ugly to have the comment smashed up to the side of the screen. instead of being indented.

[dlang-bot]

Thanks for your pull request, @jmdavis!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

[quickfur]

Personally, I like having the stars one each line clearly delineating comment text from code, but meh. It's not a big deal if Phobos is not supposed to have it.

[wilzbach]

Now the next question would be: do we recommend /// Ditto or /// ditto for new code?
Stats on Phobos are 575x on ditto and 496x on Ditto

It's obviously a subjective choice again.

[jmdavis]

I don't see much reason to care. I know that I'm completely inconsistent with regards to which I use, and sometimes I forget and wonder if I have to use ditto or Ditto or whether they both work, but a quick check of Phobos shows that they both work. I'd just as soon not require one or the other. Certainly, if one were required, I don't expect that I'd ever remember which, and I'd have to check every time.

[jmdavis]

I only added mention of Ditto to the style guide so that we're allowed to use /// with it.

[wilzbach]

Oh the reason was rather simple: whatever is written as example on this style guide will likely be the way newcomers write their code or other projects choose to base their style guide on (by saying "Ditto" and not "ditto" the upper-case variant is passively endorsed.)
So if you or someone else has a preference between "ditto" and "Ditto" - now is the time to speak.
I don't care much about this either.

[wilzbach]

I'm not sure whether I messed up the wording.
I saw a couple of Phobos functions doing this:

/**
    Sorts a range by multiple keys. The call $(D multiSort!("a.id < b.id",
    "a.date > b.date")(r)) sorts the range `r` by `id` ascending,
    and sorts elements that have the same `id` by `date`
    descending. Such a call is equivalent to $(D sort!"a.id != b.id ? a.id
    < b.id : a.date > b.date"(r)), but `multiSort` is faster because it
    does fewer comparisons (in addition to being more convenient).
    
    Returns:
        The initial range wrapped as a `SortedRange` with its predicates
        converted to an equivalent single predicate.
*/

in comparison to:

/**
Sorts a range by multiple keys. The call $(D multiSort!("a.id < b.id",
"a.date > b.date")(r)) sorts the range `r` by `id` ascending,
and sorts elements that have the same `id` by `date`
descending. Such a call is equivalent to $(D sort!"a.id != b.id ? a.id
< b.id : a.date > b.date"(r)), but `multiSort` is faster because it
does fewer comparisons (in addition to being more convenient).

Returns:
    The initial range wrapped as a `SortedRange` with its predicates
    converted to an equivalent single predicate.
 */

and of course I have observed a mixture between them too:

/**
    Sorts a range by multiple keys. The call $(D multiSort!("a.id < b.id",
    "a.date > b.date")(r)) sorts the range `r` by `id` ascending,
    and sorts elements that have the same `id` by `date`
    descending. Such a call is equivalent to $(D sort!"a.id != b.id ? a.id
    < b.id : a.date > b.date"(r)), but `multiSort` is faster because it
    does fewer comparisons (in addition to being more convenient).
    
Returns:
    The initial range wrapped as a `SortedRange` with its predicates
    converted to an equivalent single predicate.
 */

I was trying to talk about cases like the first one where the entire documentation block is indented.

[jmdavis]

The first case is exactly what I always do, and I expect that if you look, you'll find that that style is very common in Phobos.

[wilzbach]

Hehe a lot of documentation styles are common in Phobos. It contains almost every permutation imaginable.
Anyhow I didn't wanted to start a war on this, but just give newcomers a better guide.

[wilzbach]

We obviously disagree on whether indentation of should be allowed or disallowed.
I didn't wanted to start a war on this, but just give newcomers a better guide, so staying with the status quo of not being explicit on this apparently controversial topic seems like a safe choice for now.

[d-random-contributor]

leading stars or zeroes

Spaces, not zeroes.