Class references not working in method doc strings

[TheFriendlyCoder]

I've been testing dartdoc in a small project I've been working on, and found some odd behaviour with regards to hyperlinks to classes within the same project not working properly ... but only within method doc strings. Property doc strings don't seem to be affected. Below is a sample snippet to show what I mean:

/// Docstring property reference [MyObject]
Future<MyObject> get myobj async {...}

/// Docstring method reference [MyObject]
Future<int> runOperation(MyObject obj) async {

In this example, the first Doctoring will generate a hyperlink to the MyObject class (ie: from the [MyObject] reference) but the exact same syntax in the second Doctoring will generate text that looks like inline code, similar to MyObject in markdown.

[srawlins]

Can you show more complete examples? In general, doc comment references (in square brackets) do result in links. There should not be any difference between a getter and a function.

[TheFriendlyCoder]

I did a little bit more digging and it turns out the root cause of the bug isn't to do with the property vs method thing like I thought, but rather it has to do with the return value from an async method call. The gist is, whatever type(s) are returned as a Future<> do not get hyperlinked properly in the generated docs. Here is the minimal MVP to reproduce:

1. create a new empty project: dart create package .
2. create a new file Vehicle.dart with a simple definition like:

class Vehicle {
  int numWheels;

  Vehicle(this.numWheels);
}

3. Create a new file Person.dart with a simple implementation like:

class Person {
  String name;
  int age;

  Person(this.name, this.age);
}

4. Create a final file Employee.dart with an implementation like this:

import 'package:package/Person.dart';
import 'package:package/Vehicle.dart';

class Employee extends Person {
  String position;

  Employee(String name, int age, this.position) : super(name, age);

  /// Allows you to get a [Person] who might drive a [Vehicle]
  Future<Vehicle> greeting(Person p) async {
    print('Hello, my name is $name and I am $age years old. I work as a $position. Your name is ${p.name} and you are ${p.age} years old.');
    return Vehicle(4);
  }

  /// Allows you to get a [Person] who might drive a [Vehicle]
  void greeting2(Person p) async {
    print('Hello, my name is $name and I am $age years old. I work as a $position. Your name is ${p.name} and you are ${p.age} years old.');
  }
}

5. Generate the docs for the project: dart doc
6. Open the generated docs and browse to the Employee class docs, scoll to the generated output for the greeting and greeting2 methods and you should see something like this:

Note how the [Vehicle] reference in the greeting() doctoring shows up as inline code format (this method has a return type of Future<Vehicle> and the same docstring syntax for greeting2() shows up as a proper hyperlink. Same class, same docstring format, and nearly identical method signatures ... and yet the generated output is different.

[srawlins]

Great writeup @TheFriendlyCoder ! This was kind of a spooky bug, I thought surely it couldn't be that just returning a Future<X> means you can no longer refer to X in a doc comment. But that was exactly the bug. 😓 Thanks for your repros. This fix should be released soon.