The Render API overview contains an example for how to use placeholders:
https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21...
However, I think this example is incorrect on two counts:
1. '#markup'
is an array of a single string, rather than just a single string.
2. 'placeholders'
is an array of strings, rather than an array of renderable arrays.
It's difficult to devise a straightforward test to be sure that this is a mistake rather than something misinterpreted, but I've been running at the command line:
drush php-eval '$renderable = ["#markup" => ... ]; print \Drupal::service("renderer")->renderRoot($renderable);'
Respectively, the above two points raise the following two warnings:
1. "strlen() expects parameter 1 to be string, array given Unicode.php:686"; printed string is "Array"
2. "Illegal string offset '#create_placeholder' Renderer.php:163" and "Illegal string offset '#cache' Renderer.php:256"; then fatal error "Cannot use string offset as an array in /var/www/web/core/lib/Drupal/Core/Render/Renderer.php on line 256"
The following markup, on the other hand, works fine and generates the expected string "quux":
$renderable = [
"#markup" => "@foo",
"#attached" => [
"placeholders" => [
"@foo" => ["#markup" => "quux"],
]
]
];
Marking this as priority:major as either way it's quite misleading to have this in the worked examples documentation.