SeeAlso references to overloaded methods/functions: Syntax Error?

DocInsight
1

Hi:
How would one refer to a specific version of an overloaded method in the SeeAlso field?

I tried adding the signature to the reference. However, I found no way to test it. Not only that, but the generated documentation is just a skeleton without any of the descriptive fields, only generating: Syntax, Parameters, Return Value, and Implements.

When I check the documentation, I get errors released to the SeeAlso fields:
uBufferedReader.pas(228): Cref syntax error ‘uBfferedReader|TBuffererdReader|ReloadBuffer’: Expected Eof, got Bar

Thanks in advance,
Navid

2

The | is unit name separator, you just need at most one. Use . for other path. uBfferedReader|TBuffererdReader.ReloadBuffer. Use { and } for type parameters.

We will document syntax and resolving cref in details, we just need to communicate with Embarcadero about more details, e.g. overload resolution, void type, variant array type, etc.

3

Thanks. This having worked in previous versions, I am surprised by the need to communicate with Embarcadero. I still cannot get seealso or exception tags to work.

Please look at the declaration below and correct it. The cref functionality is broken.

Thanks.

unit uDocInsightTest;

interface

uses
  system.SysUtils;

type
  TFoo = class
  public
    /// <summary>
    ///   This is a Foo
    /// </summary>
    /// <remarks>
    ///   It calls Bar
    /// </remarks>
    /// <seealso cref="uDocInsightTest|TBar.Bar">
    ///   TBar.Bar
    /// </seealso>
    procedure Foo; overload;
    /// <summary>
    ///   This is another Foo
    /// </summary>
    /// <param name="Value">
    ///   a string to process
    /// </param>
    /// <exception cref="System.SysUtils|Exception">
    ///   If Value is empty
    /// </exception>
    /// <remarks>
    ///   It calls another Bar
    /// </remarks>
    /// <seealso cref="uDocInsightTest|TBar.Bar{string}">
    ///   TBar.Bar(string)
    /// </seealso>
    procedure Foo(const Value: string); overload;
  end;

  TBar = class
  public
    /// <summary>
    ///   This is Bar
    /// </summary>
    /// <remarks>
    ///   It is called by Foo
    /// </remarks>
    /// <seealso cref="uDocInsightTest|TFoo.Foo">
    ///   TFoo.Foo
    /// </seealso>
    procedure Bar; overload;
    /// <summary>
    ///   This is another Bar
    /// </summary>
    /// <param name="Value">
    ///   a string to process
    /// </param>
    /// <exception cref="System.SysUtils|Exception">
    ///   If Value is empty
    /// </exception>
    /// <remarks>
    ///   It is called by another Foo
    /// </remarks>
    /// <seealso cref="uDocInsightTest|TFoo.Foo{string}">
    ///   Tfoo.Foo(string)
    /// </seealso>
    procedure Bar(const Value: string); overload;
  end;

implementation ...
4

Thanks for your code!

XML Doc comments are embedded in dcus and It has been supported by the builtin IDE features. so it is always good to be compatible with their approach.

The full overload resolution of cref is actually scheduled in next update. To reference non-overloaded method, just ignore the signature. e.g. uDocInsightTest|TBar.Bar. To reference specific overload, use uDocInsightTest|TFoo.Foo(string).

At present, DocInsight has a limitation of that it only resolves code references to containing units within current project group. It doesn’t search global search paths. so it doesn’t resolve cref like System.SysUtils|Exception. We will improve this certainly. Actually, I plan to use Delphi compiler (Delphi 11 or higher) to produce metadata for delphi packages so it will show more accuracy results. In this approach, it will be more reliable to resolve code references to system and third-party libraries. (Scheduled in 6.1.0-insider)