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 478d7c7): 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. |
… into 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.
| description: Learn about doc comment references and their syntax. | ||
| --- | ||
|
|
||
| Doc comments can contain references to various code elements. A library member |
There was a problem hiding this comment.
Describing doc comment references as referring to "elements" makes sense to me and I believe is what we've always said, but is that because of its implementation ties to the analyzer and our familiarity with it? I'm not necessarily saying we shouldn't use the term, but I just want to make sure it's the best term to use.
I can find very few cases in user-facing docs where we use the term "element" like this. Never do we say "code element". In fact, we are careful to use the term as it already has a few meanings (elements in a collection, collection literal elements, HTML elements, etc).
As a side note, comment_references lint docs use "in-scope identifiers".
@bwilkerson for your thoughts, particularly based on writing diagnostic messages.
\cc @eernstg For your insight :)
There was a problem hiding this comment.
I'll stick to "identifiers" instead of "code elements" for now. Good call. I think "element" might be more correct in other cases. For example, an identifier is not referred to, a class is, via it's identifier. It is messy though.
Work towards #6076
This does not discuss "doc imports"; I'd like that to be a separate addition.
Staged: https://dart-dev--pr6080-doc-comment-references-37rf6iwi.web.app/tools/doc-comment-references