Initial documentation for doc comment references #6080
Conversation
|
CC @dart-lang/analyzer-team for any comments. |
|
Visit the preview URL for this PR (updated for commit 3037c83): https://dart-dev--pr6080-doc-comment-references-cx0x9ulm.web.app |
|
This is lovely that it is staged at https://dart-dev--pr6080-doc-comment-references-37rf6iwi.web.app/tools/doc-comment-references. |
|
Ready for review. |
There was a problem hiding this comment.
Thanks so much @srawlins! It's super exciting to finally have this officially documented.
These docs look great to me and could land in the current state if you prefer, but I have a few comments, questions, and enhancements for you to consider. The main thing is that big blocks of text can be intimidating and are often skipped over, especially if someone knows something exists and just wants to know the syntax of it.
Feel free to push back on any of my comments or defer them for later (or for me).
I'll try to open a separate PR this week to explore how we can layout this page alongside other doc-comment related pages.
|
Sorry for the delay; this is ready for review again. 😀 |
… into doc-comment-references
| If the element does not have a documentation page (for example, a function | ||
| parameter, a type variable, or a private class), then no link is created. | ||
|
|
||
| ## What can be referenced |
There was a problem hiding this comment.
Thanks for exploring this! It seems a bit cramped with the table formatting, so maybe let's drop the table for now. I can revisit this with some different formats or custom styles as follow up.
| If the element does not have a documentation page (for example, a function | ||
| parameter, a type variable, or a private class), then no link is created. | ||
|
|
||
| ## What can be referenced |
There was a problem hiding this comment.
SG. I'm sure there's a good solution in here. Maybe just experiment with different table layouts.
|
Thanks again Sam! This is now live with a redirect to it that tools or external docs can reference: https://dart.dev/to/doc-comment-references I hope to get time to work on some related docs soon so it has a place it live in the sidenav. |
Resolves #6076
This does not discuss "doc imports"; I'd like that to be a separate addition.
Staged: https://dart-dev--pr6080-doc-comment-references-cx0x9ulm.web.app/tools/doc-comment-references