Convert nonstandard use of “(optional)” in @param DocBlocks

[coffee2code]

A number of @param DocBlock descriptions use "(optional)" to denote a parameter as being optional. Additionally, its use is inconsistent, sometimes appearing at the start of the parameter description and sometimes at the end.

The ​inline documentation standards require that an optional parameter should be denoted with "Optional." at the beginning of the description.

Attached patch corrects all existing occurrences of this nonstandard notation.

Since those doc lines were changing anyway, I also went ahead and made some very minor formatting tweaks to those modified lines and/or to immediately adjacent lines. This includes: adding ending period for descriptions, stating the default value if not done so, correcting the way some default values were stated, aligning @param elements, and a few text fixes.

[coffee2code]

Patch mentioned in ticket description.

[DrewAPicture]

In 30753:

Convert various uses of (optional) in core parameter descriptions to use the style prescribed in the inline documentation standards for PHP.

The style for marking parameters optional in inline PHP docs is: @param type $var Optional. Description. Accepts. Default., where Accepts can be omitted on a case-by-case basis.

Props coffee2code.
Fixes #30591.

[TobiasBg]

30591-typo.diff​ fixes a typo in [30753].

[DrewAPicture]

In 30755:

Fix a typo in the return description for get_sample_permalink().

Props TobiasBg.
Fixes #30591.