Skip to main content
42 votes
Accepted

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

The standard way to deal with a certain part of text that needs to stand out from other parts of text is through typographic means: using italics, boldface, size, capitalization, color, different font ...
Jörg W Mittag's user avatar
20 votes

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 ...
Bergi's user avatar
  • 1,333
8 votes

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

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 ...
Petr's user avatar
  • 197
4 votes

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

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 ...
Fabio says Reinstate Monica's user avatar
2 votes

Should usage examples in XML documentation be explicitly tested?

Personally, yes, I believe, they should be tested. A lot of people say that one of the bad things about documentation comments is that they are not checked by the compiler. Well, here you have at ...
Jörg W Mittag's user avatar
1 vote

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

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 -->); </...
MSalters's user avatar
  • 8,812

Only top scored, non community-wiki answers of a minimum length are eligible