@link tag

1. Introduction

In a description of one item you can link to another item using the @link tag. The links are converted to be clickable references suitable for the output format.

Example:

const
  MaxFactorialArgument = 20;

{ Calculate factorial of n, @code(n!).
  Always call this function with
  n <= @link(MaxFactorialArgument),
  otherwise result will not fit in Int64 type. }
function SmallFactorial(n: Integer): Int64;

You can link to any item in your codebase, including:

  • routines (procedures, functions),

  • constants,

  • types,

  • enumeration types and enumerations members,

  • variables,

  • properties,

  • fields,

  • methods,

  • units,

  • classes, interfaces, records,

  • and so on — really every Pascal item that PasDoc found in the source code.

2. Qualifying the linked item with class name, unit name, etc.

When resolving links, PasDoc follows similar namespace rules as the compiler. For example, within a class, you can link to its methods and properties directly (without specifying the class name). From the outside, you need to specify the class name, like @link(TMyClass.MyMethod). You can qualify the link even more, with a unit name.

For example:

unit MyUnit;
interface

type
  { Create an instance of this, then use @link(MyMethod) to do something. }
  TMyClass = class
    { Sets @link(MyProperty) to 'foo'. }
    procedure MyMethod;
    { Change this directly or by calling @link(MyMethod). }
    property MyProperty: String read FMyProperty write FMyProperty;
  end;

{ Creates an instance of @link(TMyClass)
  and calls @link(TMyClass.MyMethod). }
procedure SomeProcedure;

{ Creates @link(SomeOtherUnit.TSomeOtherClass)
  and calls @link(SomeUnit.TSomeOtherClass.SomeOtherMethod). }
procedure AnotherProcedure;

implementation
end.

3. Explicit caption of a link

By default, the link looks just like the name of the item it links to. And the multipart links look can be customized using the --link-look CommandLine option.

You can also specify an explicit caption for this link, simply by putting a space after your link target and then typing the caption. E.g.

@link(TMyClass.MyMethod This is a link to MyMethod in TMyClass)

An example use for such an explicit caption is if you have a class TMemo that has a property named Lines that returns an instance of a class TStringList. You want to document routine TMemo.Clear, that calls Lines.Clear and then does some repainting stuff. So you want to link in your description to TStringList.Clear, but you want the link to show as Lines.Clear. You can do it by writing a description like

type
  TMemo = class
    property Lines: TStringList read FLines;

    { This method calls @link(TStringList.Clear Lines.Clear)
      and then does some repainting stuff. }
    procedure Clear;
  end;

4. Disambiguate links to overloaded routines

If you have overloaded routines, you can disambiguate the link by specifying the parameter types. For example, if you have two overloaded procedures Foo, one with no parameters and another with an Integer parameter, you can link to the first one using @link(Foo()) and to the second one using @link(Foo(Integer)). Like this:

procedure Foo; overload;
procedure Foo(x: Integer); overload;

{ This calls @link(Foo()) and then @link(Foo(Integer)). }
procedure Bar;

You can still specify a caption after a space:

procedure Foo; overload;
procedure Foo(x: Integer); overload;

{ This calls @link(Foo() Foo without parameters)
  and then @link(Foo(Integer) Foo with an Integer parameter). }
procedure Bar;