Conversation
| /// <item>Scopes returned will always have at least one non-empty property value in them.</item> | ||
| /// <item>Symbols may be imported, but may not necessarily be available at that location (for example, an alias | ||
| /// symbol hidden by another symbol).</item> | ||
| /// <item><description>Scopes returned will always have at least one non-empty property value in them.</description></item> |
There was a problem hiding this comment.
It seems unfortunate to require <description> in <item>s. We will likely need to fix this again at some point in the future unless we also create a linter for this.
Would it be possible to instead fix the rendering to handle the current form?
There was a problem hiding this comment.
@kexugit @huangmin-ms Can you comment on Jan's question? What's the likelihood of a fix?
There was a problem hiding this comment.
The docs here do state that <description> is required. However, that requirement does seem to be specific to the rendering on Learn, as the list renders correctly in IntelliSense without <description>:
(cc @BillWagner in case the doc should be updated to remove that requirement)
There was a problem hiding this comment.
@gewarren unless I'm reading them wrong those docs only indicate that description is required when making a definition list. This is not a definition list, there is no listheader tag. This is just a normal bulleted list.
There was a problem hiding this comment.
@333fred I think you might have read them wrong, because they state that description is required for table items too
There was a problem hiding this comment.
Okay, I logged https://portal.microsofticm.com/imp/v5/incidents/details/731178896/summary for the reference docs team to address.
There was a problem hiding this comment.
Given that it will likely be 6+ months (at least) for this to be fixed (many ref bugs don't ever get fixed), do you want to take this PR meanwhile?
There was a problem hiding this comment.
Okay, I logged https://portal.microsofticm.com/imp/v5/incidents/details/731178896/summary for the reference docs team to address.
The fix is in progress. Will update the incident once it is deployed.
|
I def agree with Jan. This feels like an unfortunate requirement that we are likely to have many violations around in the future. |
|
Yeah, 100% agreed with Cyrus and Jan. This very much feels like a learn bug, not something to resolve in source. |
Add <description> tags to list items. Will fix dotnet/dotnet-api-docs#12200 once the CI is run again.