Is there a way to escape a closing bracket for comments?

Question

I'm adding comments to my Delphi code for documentation. One of the things I'm trying to document is the JSON structure, so I'm trying to put sample JSON data commented in the code. However, JSON widely uses the squiggly brackets { }, which coincidentally is also used for comments in Delphi.

Because of this, I can't figure out a way to add these comments. Usually for documentation comment blocks I use { }, for example:

{
  This unit does this and that.

  Use TSomeComponent to do bla bla
}

When I try to document JSON data, the closing bracket } ends the comment - even if the line is prefixed with the single-line comment //, so even this doesn't work:

{
  This is how the JSON structure looks:

//    {
//      "some_string": "value",
//      "some_object": {
//        "something": 123
//      }, //<-- Compiler detects this comma
//      "something_else": "some other string"
//    }
}

As soon as there's a closing bracket }, the commented line becomes uncommented, even if it's prefixed with the two slashes. So Delphi picks up the comma after this bracket. So in the end, I cannot figure out any way in which I can document JSON samples inside my code.

I even tried using (* *) around the JSON block but still no luck.

Is there any way around this or am I stuck with it?

Answer 1

I discovered the solution while I was typing this question, so now I'm answering it Q/A style...

When the comment block first starts as in the code in the question above, it starts with an opening bracket {. So, the compiler is desperately looking to find a closing bracket, even if that closing bracket is in another commented line of code. But, if every line in this comment block begins with two slashes // instead of an opening bracket {, then the compiler will not be looking for the closing bracket }. So, instead of the code in the question above, this is how it should be written:

//  This is how the JSON structure looks:
//  
//    {
//      "some_string": "value",
//      "some_object": {
//        "something": 123
//      },
//      "something_else": "some other string"
//    }

So as long as you don't start the comment block with an opening bracket, then the compiler won't try to end the comment block when it finds a closing bracket.

Also, using (* *) should work fine, as long as you don't use it after you've already used {. Enclose the entire block with (* and *) and the compiler will ignore any { or } inside, like so:

(*
  This is how the JSON structure looks:

    {
      "some_string": "value",
      "some_object": {
        "something": 123
      },
      "something_else": "some other string"
    }
*)

Essentially, from the moment you begin one comment, whether it be //, {, or (*, it will ignore any further opening of any other type of comment - it will only be looking for the end of its own comment type. So // will look for the end of the line, { will look for }, and (* will look for *).