# Link API symbols and topics

Use `<see>` for an inline link and `<seealso>` for an entry in the generated related-links section. Choose the target attribute by what you are linking to:

Attribute | Target
--- | ---
`cref` | Symbol that Delphi source analysis can resolve
`href` | External page
`xref` | Topic exported by the DocInsight documentation system

## Link to a Delphi symbol

Use `cref` for a symbol in the analyzed Delphi compilation environment:

pascal

    /// <summary>
    ///   Creates a new <see cref="IList{T}" /> instance.
    /// </summary>
    class function CreateList<T>: IList<T>; static;

DocInsight resolves `cref` by Delphi symbol identity rather than by a generated output path. When the referenced symbol has a published API topic, the generated link points to that topic.

## Link to an external page

Use `href` for an external URL:

pascal

    /// <seealso href="https://docinsight.github.io/mylibrary/">
    ///   MyLibrary documentation
    /// </seealso>

## Link to a documentation topic

Use `xref` for an explicit DocInsight cross-reference. The value contains the target Xref namespace and source-owned topic identity. Delphi API topics use the effective namespace assigned to their Delphi project by the source's `xref` settings:

pascal

    /// <seealso xref="mylibrary/MyLibrary.Collections/TCollections">
    ///   TCollections
    /// </seealso>

When `project.name` is `mylibrary` and the source has no namespace override, `mylibrary` is the default namespace. The Delphi content name, such as `api`, does not become part of the Xref. Package local IDs start at the unit. Program and library local IDs also include the Delphi project name; use an exact project namespace override when that would produce a redundant Xref such as `mylibrary/mylibrary.tests/...`. The override shortens it to `mylibrary.tests/...`.

Markdown topics continue to use their content entry name as the namespace, so an API comment can link to a guide in the same documentation project like this:

pascal

    /// <summary>
    ///   See the <see xref="docs/collections">collections guide</see> for usage patterns.
    /// </summary>
    /// <seealso xref="docs/collections">
    ///   Collections guide
    /// </seealso>

For the Delphi source namespace configuration and project override precedence, see Configure Xref namespaces. For Markdown topic identities, see Add links and cross-references.

## Link to an image

Use `<img>` with a relative `src` path to include an image in XML documentation. DocInsight resolves the path from the `.pas` file containing the comment:

pascal

    /// <remarks>
    ///   The following diagram shows the collection hierarchy.
    ///   <img src="./images/collection-hierarchy.png" alt="MyLibrary collection hierarchy" />
    /// </remarks>

The `src` value must be a relative filesystem path. Paths beginning with `/`, operating-system absolute paths, and URLs are not supported. The resolved image must remain inside the configured Delphi source root; paths and symbolic links that escape it are rejected. For ownership and publishing rules, see Content-local assets.

## Refer to parameters and type parameters

Use `<paramref>` and `<typeparamref>` for parameter and type-parameter names in inline text:

pascal

    /// <summary>
    ///   Gets the value at the specified <paramref name="Index" />.
    /// </summary>
    function GetItem(Index: Integer): T;