Document the preferred Phobos documentation style

[wilzbach]

Follow-up to dlang/druntime#2054.
I'm fully aware that Phobos is a wild mixture of a many, many styles.
This PR won't do any reformatting of Phobos, but tries to define best practices for writing new documentation header as it seems to come up often lately.

--- edit:

Obviously this entire topic is purely subjective and emotional, but the idea here is to find a common ground that can be recommended to newcomers.

[dlang-bot]

Thanks for your pull request, @wilzbach!

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.

[wilzbach]

This is probably the most controversial bit.

/**
Capitalize the first character of $(D s) and convert the rest of $(D s) to
lowercase.

Params:
    input = The string to _capitalize.

Returns:
    The capitalized string.

See_Also:
     $(REF asCapitalized, std,uni) for a lazy range version that doesn't allocate memory
*/

vs.

/**
 * Capitalize the first character of $(D s) and convert the rest of $(D s) to
 * lowercase.
 *
 * Params:
 *     input = The string to _capitalize.
 *
 * Returns:
 *     The capitalized string.
 *
 * See_Also:
 *      $(REF asCapitalized, std,uni) for a lazy range version that doesn't allocate memory
 */

While I can understand that the latter is used for symbols in structs, classes etc., I generally don't like the extra work and noise added by the stars.

[jmdavis]

If we're going to require /++ +/ or /** */, can we please require /++ +/:

#2133

[quickfur]

AFAIK, the vast majority of ddocs in Phobos use /** */. Changing that to /++ +/ is going to introduce huge amounts of churn converting from the former to the latter.

Plus, I don't think /++ +/ gives us very much advantage at all... the only time you'd want comments inside a ddoc is when there are code examples, and Phobos nowadays almost exclusively uses ddoc'd unittests where any comments are actual comments rather than comments embedded inside ddoc comments. Not to mention that comments in code examples tend to be brief (otherwise they really belong in the ddoc text rather than inside the example), so // would serve just as well.

[jmdavis]

Both styles are used heavily in Phobos, so if we want to normalize the docs, we'd be changing a ton of code either way. I'd be fine with not requiring one over the other, but I see zero advantage to /** */ if we're going to require one or the other.

[andralex]

both are good stars are preferred

[jmdavis]

If both are considered okay, then we shouldn't require one or the other in the style guide but should just state that we don't want leading stars or pluses on each line.

On a related note, I don't know why we'd want to not indent the documentation. I believe that most of the existing ddoc comments are indented, though fortunately, most don't use the leading stars.

[jmdavis]

#2134

[wilzbach]

I explicitly wanted to allow this:

Returns: The capitalized string.

As it's a lot more concise than:

Returns:
     The capitalized string.

[JinShil]

Suggestion: Every public symbol should be exposed in the documentation:

[JinShil]

... if it spans ...

[JinShil]

Sigh... Reviewing an already merged PR 😆

[andralex]

:) @JinShil feel free to make a followup and merge directly