Many unresolved-doc-reference warnings for generic types

[kevmoo]

This is a lot of noise when trying to find real bugs in doc comments.

Also, in the case of Future<Response> below, it'd be nice if Response was linked to the right type in the package.

Just for pkg/shelf:

unresolved doc reference [Future<Response>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [List<int>]
unresolved doc reference [Stream<HttpRequest>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [Stream<List<int>>]
unresolved doc reference [StreamChannel<List<int>>]

[jcollins-g]

We don't currently support generic type resolution in comment references, but this could be added. I agree it is annoying; P2.

[kevmoo]

FYI: this is not just comment references. It's also with extends, argument, etc... at least AFAICT

[jcollins-g]

@kevmoo could you be more specific on these cases? Extends and arguments are mentioned and handled at least partially by dartdoc, so it isn't like we're starting from nothing. But if there are particular edge cases that need handling we can do that.

[kevmoo]

Running 29a676a

against https://github.com/dart-lang/shelf

yields (json)

{"level":"INFO","message":"Generating documentation for 'shelf' into //shelf/doc/api/"}
{"level":"INFO","message":"parsing lib/shelf.dart..."}
{"level":"INFO","message":"parsing lib/shelf_io.dart..."}
{"level":"INFO","message":"Initialized dartdoc with 3 libraries in 5.2 seconds"}
{"level":"INFO","message":"documenting shelf"}
{"level":"INFO","message":"Generating docs for library shelf from package:shelf/shelf.dart..."}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Future<Response>], from shelf.createMiddleware: (file:////shelf/lib/src/middleware.dart:49:12)","text":"  warning: unresolved doc reference [Future<Response>], from shelf.createMiddleware: (file:////shelf/lib/src/middleware.dart:49:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Request: (file:////shelf/lib/src/request.dart:128:3)","text":"  warning: unresolved doc reference [List<int>], from shelf.Request: (file:////shelf/lib/src/request.dart:128:3)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Request: (file:////shelf/lib/src/request.dart:128:3)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Request: (file:////shelf/lib/src/request.dart:128:3)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Request.change: (file:////shelf/lib/src/request.dart:211:11)","text":"  warning: unresolved doc reference [List<int>], from shelf.Request.change: (file:////shelf/lib/src/request.dart:211:11)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Request.change: (file:////shelf/lib/src/request.dart:211:11)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Request.change: (file:////shelf/lib/src/request.dart:211:11)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [StreamChannel<List<int>>], from shelf.Request.hijack: (file:////shelf/lib/src/request.dart:244:8)","text":"  warning: unresolved doc reference [StreamChannel<List<int>>], from shelf.Request.hijack: (file:////shelf/lib/src/request.dart:244:8)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response: (file:////shelf/lib/src/response.dart:280:3)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response: (file:////shelf/lib/src/response.dart:280:3)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response: (file:////shelf/lib/src/response.dart:280:3)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response: (file:////shelf/lib/src/response.dart:280:3)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.forbidden: (file:////shelf/lib/src/response.dart:196:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.forbidden: (file:////shelf/lib/src/response.dart:196:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.forbidden: (file:////shelf/lib/src/response.dart:196:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.forbidden: (file:////shelf/lib/src/response.dart:196:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.found: (file:////shelf/lib/src/response.dart:117:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.found: (file:////shelf/lib/src/response.dart:117:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.found: (file:////shelf/lib/src/response.dart:117:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.found: (file:////shelf/lib/src/response.dart:117:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.internalServerError: (file:////shelf/lib/src/response.dart:252:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.internalServerError: (file:////shelf/lib/src/response.dart:252:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.internalServerError: (file:////shelf/lib/src/response.dart:252:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.internalServerError: (file:////shelf/lib/src/response.dart:252:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.movedPermanently: (file:////shelf/lib/src/response.dart:89:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.movedPermanently: (file:////shelf/lib/src/response.dart:89:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.movedPermanently: (file:////shelf/lib/src/response.dart:89:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.movedPermanently: (file:////shelf/lib/src/response.dart:89:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.notFound: (file:////shelf/lib/src/response.dart:224:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.notFound: (file:////shelf/lib/src/response.dart:224:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.notFound: (file:////shelf/lib/src/response.dart:224:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.notFound: (file:////shelf/lib/src/response.dart:224:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.ok: (file:////shelf/lib/src/response.dart:62:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.ok: (file:////shelf/lib/src/response.dart:62:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.ok: (file:////shelf/lib/src/response.dart:62:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.ok: (file:////shelf/lib/src/response.dart:62:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.seeOther: (file:////shelf/lib/src/response.dart:146:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.seeOther: (file:////shelf/lib/src/response.dart:146:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.seeOther: (file:////shelf/lib/src/response.dart:146:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.seeOther: (file:////shelf/lib/src/response.dart:146:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [List<int>], from shelf.Response.change: (file:////shelf/lib/src/response.dart:306:12)","text":"  warning: unresolved doc reference [List<int>], from shelf.Response.change: (file:////shelf/lib/src/response.dart:306:12)"}}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<List<int>>], from shelf.Response.change: (file:////shelf/lib/src/response.dart:306:12)","text":"  warning: unresolved doc reference [Stream<List<int>>], from shelf.Response.change: (file:////shelf/lib/src/response.dart:306:12)"}}
{"level":"INFO","message":"Generating docs for library shelf_io from package:shelf/shelf_io.dart..."}
{"level":"WARNING","data":{"type":"warning","kind":"unresolved-doc-reference","message":"unresolved doc reference [Stream<HttpRequest>], from shelf_io.serveRequests: (file:////shelf/lib/shelf_io.dart:62:6)","text":"  warning: unresolved doc reference [Stream<HttpRequest>], from shelf_io.serveRequests: (file:////shelf/lib/shelf_io.dart:62:6)"}}
{"level":"INFO","message":"Validating docs..."}
{"level":"WARNING","message":"found 25 warnings and 0 errors"}
{"level":"INFO","message":"Documented 2 public libraries in 1.5 seconds"}
{"level":"INFO","message":"Success! Docs generated into //shelf/doc/api"}

[CaptainIRS]

I think this issue can be closed as the references are resolved correctly from 7f46b5d (#2397).

Before 7f46b5d	From 7f46b5d

[jcollins-g]

Done!