Add missing parameter documentation to \Drupal\Component\Utility\Random::image()

Looks good. Patch is doc change only.

Good spot on the missing parameter documentation.

+++ b/core/lib/Drupal/Component/Utility/Random.php
@@ -262,8 +262,12 @@ public function paragraphs($paragraph_count = 12) {
+   *   The minimal image resolution, formatted as '[width]x[height]', e.g.
+   *   '640x480', if you want a min resolution of 640px width and 480px height.
...
+   *   The maximal image resolution, formatted as '[width]x[height]', e.g.
+   *   '640x480', if you want a max resolution of 640px width and 480px height.

It should say "minimum" and "maximum" (which have slightly different meanings than "minimal" and "maximal"). We should use the full word instead of "min" and "max" later in the description as well.

The sentences are also kind of a run-on. We should split it into two sentences.

Finally, is there an existing description of data in this width x height format elsewhere in core that we should make it consistent with? The square brackets can confuse users since we are using them to denote "replace '[width]' with the number" but that is not actually clear or consistent. In general we should avoid such pseudo-delimiters because users can think they are part of the actual string format.

Actually this also calls into question why we do not allow passing separate min_width, min_height, max_width, and max_height parameters rather than this weird special string format. :) But that is out of scope for this issue, so would need to be discussed in a followup if anything.

Also, thinking about the scope of this issue in terms of: https://www.drupal.org/core/scope#coding-standards

This issue is adding missing parameter documentation. While missing parameter documentation is itself a coding standards error, adding that documentation needs to be done by writing it, which means understanding the concepts involved. So the current scope of this patch, limited to one concept, also makes sense.

However, we should make sure we're adding all the missing parameter documentation for this specific concept. Can we check whether there is any other missing documentation in the Random component? Writing that documentation together would work best.

Thanks @agoradesign!

@xjm Here is the new patch.

is there an existing description of data in this width x height format elsewhere in core that we should make it consistent with?

I found file which have existing description of data in this width x height format. The file is file.module :) .

 * @param string|int $maximum_dimensions
 *   (optional) A string in the form WIDTHxHEIGHT; for example, '640x480' or
 *   '85x85'. If an image toolkit is installed, the image will be resized down
 *   to these dimensions. A value of zero (the default) indicates no restriction
 *   on size, so no resizing will be attempted.

Tested via #6.
It's showing the added text. This can be moved to RTBC

A description for these parameters was added in #3076644: Mistake in the comment documenting the "image" method of the "Random" utility class.. The text is different than what is in the patch, but the meaning is the same. Closing as a duplicate.