CODEWITHSUNDEEP
dart
Argenti Apparatus
Argenti Apparatus

Reputation: 4013

How to refer to constructors and operators in dartdoc?

The Dart Language Tour covers documentation comments, and says:

Inside a documentation comment, the Dart compiler ignores all text unless it is enclosed in brackets. Using brackets, you can refer to classes, methods, fields, top-level variables, functions, and parameters. The names in brackets are resolved in the lexical scope of the documented program element.

I potentially want to be able to refer to anything in scope, but I'm having trouble working out how to refer to named and unnamed constructors, and operators.

I created a test library with documentation comments:

/// # Thingy
/// 
/// Blah [GLOBAL] blah [function] blah [Thingy] blah [Thingy.property] blah
/// [Thingy.virtualProperty] blah [Thingy.named]  blah [Thingy.method]
/// blah [Thingy.operator+].
/// Try these: [Thingy.named()] blah [Thingy.()] blah [Thingy()].

library Thingy;

const int GLOBAL = 0;

void function(int arg) {}

/// A class.
/// 
/// Blah [GLOBAL] blah [function] blah [Thingy] blah [property] blah
/// [virtualProperty] blah [named] blah [method] blah [operator+].
/// Try these: [Thingy.named()] blah [Thingy.()] blah [Thingy()].
class Thingy {

  int property;

  int get virtualProperty => 0;
  set virtualProperty(int arg) {}

  Thingy(int arg) {}
  Thingy.named(int arg) {}

  /// A method.
  /// 
  /// Blah [GLOBAL] blah [function] blah [Thingy] blah [property] blah
  /// [virtualProperty] blah [named] blah [method] blah [operator+] blah
  /// [arg].
  /// Try these: [Thingy.named()] blah [Thingy.()] blah [Thingy()].
  void method(int arg) {}

  Thingy operator+(int arg) => null;
}

The library, class and method documentation generated by Dartdoc come out looking like:

Blah GLOBAL blah function blah Thingy blah property blah virtualProperty blah named blah method blah operator+ ...

Try these: Thingy.named blah Thingy.() blah Thingy().

(Not actual Dartdoc output - just what it looks like. Dart language tour URL used to simulate the links.)

Most of the references work, but how can I refer to constructors and operators?

Upvotes: 4

Views: 524

Answers (3)

Justin McCandless
Justin McCandless

Reputation: 681

The accepted answer is out of date.

Now, to reference the main unnamed constructor:

/// [MyClass.new]

And to reference a named constructor:

/// [MyClass.someNamedConstructor]

This analyzer message explains it.

Upvotes: 1

Argenti Apparatus
Argenti Apparatus

Reputation: 4013

Effective Dart: Documentation documents dart documentation comments, including references.

Upvotes: 0

Günter Zöchbauer
Günter Zöchbauer

Reputation: 657937

Constructors are referred to with new

/// [new MyClass] 
/// [new MyClass.someNamedConstructor]

I haven't found a way to reference operators

/// [operator ==] or [==] seem not to work

I created https://github.com/dart-lang/dartdoc/issues/1087

Upvotes: 4

Related Questions