@longCode tag

Use the tag @longCode to include a piece of Pascal code in the documentation. This is usually a short example how to use the identifier you’re documenting.

The Pascal code will be displayed:

  • using a fixed-width font,

  • the formatting inside (whitespaces, like spaces and newlines) will be preserved (except removing a common prefix of whitespace from all the lines, see below),

  • and the code will be syntax-highlighted, using colors and bold/italic to show the structure of the code.

Example usage:

(*Some example use of TForm.OnCreate :

  @longCode(
  procedure TForm1.FormCreate(Sender: TObject);
  var
    I: Integer;
  begin
    // Note that your comments are styled.
    {$H+}
    // You can even include compiler directives.
    // reserved words are formatted in bold.
    for I := 1 to 10 do
    begin
      It is OK to include pseudo-code like this line.
      // It will be formatted as if it were meaningful pascal code.
    end;
  end;
  )
*)
property OnCreate: TNotifyEvent read FOnCreate write FOnCreate;

This example will result in a description that looks like this in HTML (with the default CSS):

Sunset

The @longCode tag does not expand the given parameter (see TagsParameters), which means that:

  • Other @-tags are not expanded inside the @longCode contents,

  • paragraphs are not inserted and in general whitespace has no special meaning,

  • you can simply write a single @ char to get it in the output (no need to double it, like @@). For example this is valid:

    { Do something with the pointer to an Integer. Use like this:
  @longCode(
    var
      MyInteger: Integer;
    begin
      Foo(@MyInteger);
    end;
  ) }
procedure Foo(const A: PInteger);

To make it comfortable to write, we remove "initial whitespace" from all the lines in the included Pascal code. To determine what is exactly the "initial whitespace", we find the longest common prefix of all lines in the @longCode parameter that contains only whitespace, and then we remove it from all the lines. This way all the following examples are equivalent:

{ @longCode(
    Foo;
    Bar;
  )
}
procedure Sample1;

{ @longCode(
  Foo;
  Bar;
  )
}
procedure Sample2;

{ @longCode(
Foo;
Bar;
  )
}
procedure Sample3;

    { @longCode(
        Foo;
        Bar;
      )
    }
    procedure Sample4;

The contents of the @longCode tag span to the matching closing parenthesis, just like for all other @tags.

In the past, @longCode required a special marker character at the beginning and at the end of the text (the convention was to use # for this, but any character was valid). This is no longer necessary and is just ignored by the current pasdoc versions. For backward compatibility, if the first and last character of the @longCode parameter (before any trimming and indentation removal) are the same, it is treated as a marker character and removed. You will usually not notice this — as these characters are almost always whitespace or are different.