What are better ways of indicating "insert actual value in place of the placeholder value" in documentation?

I fully support Jörg's answer and recommend the usage of <var> elements with appropriate styling.

However, to prevent the mistake of copying the square brackets and writing an array literal, you could also use a different bracket type. While square brackets are the most common representation for "fill-in" parameters¹, you can also use <…> angle brackets or {…} curly braces (which are common in template syntax). Those have the advantage of producing a syntax error in JS if they do not get replaced.

Another option is to use a syntactically valid format in the code², but with a value that is void or semantically invalid. It should be easily distinguishable as an example value, like "customer-ref.example.com", "00000000-0000-0000-0000-000000000000" or "12345678-1234-5678-1234-567812345678". In your code, you may even throw an exception with an explanatory message when it is called with this sentinel value passed.

_{1: not to be confused with their usage in API signature documentation, where they mark up optional parameters.
2: of course still with the instruction to replace that value by the customer reference.}

A bit of a frame challenge.

What you have made is a software library. So the documentation should not just provide examples, it should document the customer-facing API of the library. There are millions of examples of API documentation, but no decent API documentation relies on examples only. And even the examples are usually with some made-up values, not with placeholder.

So you can write something like:

The library provides a single global class instance, OurService.

This class has the following methods:

• initDiary(customerReference: string)

  Accepts one paremeter, the customer reference string (in "CUSTOMER1234" format). Initializes the diary. May be called only once before a corresponding call to closeDiary.

• closeDiary()

  Closes the previously-initialized diary.

• etc....

Example:

<script>
    OurService.initDiary("CUSTOMER1234");
    someButton.onClick = closeDiary;
</script>

This is a more-or-less standard way of describing APIs that every developer should understand.

Also, if do not want do document all the methods and parameters of your classes, then maybe you should create a customer-facing wrapper that will expose only the methods and parameters that you want to expose.

Here's an overview of the approaches taken by some of the tech giants:

• Microsoft shows the syntax of Powershell cmdlets (e.g. Get-TimeZone) using angle brackets whenever an argument must be specified by the user, and as placeholder they use the argument's type , such as <string[]>:

  Get-TimeZone
     [[-Name] <String[]>]
     [<CommonParameters>]
  

• Git's documentation uses angle brackets for variables:

  git branch (-m | -M) [<oldbranch>] <newbranch>
  

• Grep's manual on gnu.org writes the placeholders in italics:

  -f file
  --file=file

• Google has a very nice solution which makes heavy use of text formatting: when describing commands, the docs for Cloud Shell write variables in italics and use a different colour and background, and then when they show the code they write the placeholder using the same colour, underlining it with some dots and adding a pencil icon which can be clicked to edit the value:

  

• Some companies sidestep the problem entirely, as they do not provide a synopsis with placeholders; instead, they always give examples using real values:

  • IBM in their tutorial on AWK

  • Red Hat in their article about essential Linux commands. There's one exception, though: when talking about the kill command they use angle brackets:

    $ kill -15 <PID>
    

  • Apple in their shell scripting tutorial. Again, there's one exception: when talking about case they use some placeholders

    case expression in
        [(] value | value | value | ... ) command; command; ... ;;
        [(] value | value | value | ... ) command; command; ... ;;
        ...
    esac
    

    In this case the formatting is the same, so it is up to the user to figure out that these are placeholders. The context makes it clear, and the fact that these keywords are repeated helps.

An option I've used is to insert an actual comment. Many editors will use a different color for this, so it stands out.

<script>
    OurService.initDiary(<!-- CustomerReference -->);
</script>

If this is overlooked, you can reasonably expect an error message along the line of "Missing argument in call to initDiary. 1 argument expected, but 0 provided."

Rip a page out of Gerrit’s playbook:

Or YouTube’s playbook:

In other words, don’t ask your customers to replace any placeholders. Give them the actual, literal code they need to insert, ready to copy-paste, save and forget it. Computers exist to do clerical work like this, so let them do it. Put it somewhere on their account page when they log in to your service, and have documentation direct them there. That simple.

(Those are not particularly fresh screenshots, but it doesn’t matter. Principle remains the same.)

Failing that, you can have a section on your site that lets the user enter their reference number and it spits back a ready-made snippet to copy-paste. Something as simple as this will do:

const input = document.getElementById('refnum');
const output = document.getElementById('output');
const inputSec = document.getElementById('refnum-section');
const outputSec = document.getElementById('output-section');

inputSec.style.display = '';
outputSec.style.display = 'none';

input.addEventListener('input', ev => {
    outputSec.style.display = input.value !== '' ? '' : 'none';
    output.textContent = JSON.stringify(input.value);
});

<p id="refnum-section" style="display: none;">
  Enter your customer reference number here:
  <input id="refnum" placeholder="123456789-ABCDEFGHI">

<div id="output-section">
  <p> Insert this snippet into your site:

  <pre>&lt;script type="text/javascript">
  OurService.initDiary(<span id="output"><var>"your reference number here"</var></span>);
&lt;/script></pre>
</div>

Modulo, of course, however you can fit the above interface into your shiny frontend framework of the week. (This would have been a runnable snippet, but those aren’t enabled on this site for some reason.)