Repository navigation
Links to the same symbol should not be rendered as links #3149
Description
If I have a symbol with documentation:
/// The style to use for the [helperText].
///
/// If [helperStyle] is a [MaterialStateTextStyle], then the effective
/// text style can depend on the [MaterialState.focused] state, i.e.
/// if the [TextField] is focused or not.
final TextStyle? helperStyle;Then, when the page is rendered, the bracketed reference to [helperStyle] is rendered as a link to the same page that the user is already viewing.
This means that to have "correctly" authored documentation for that, then we need to write it as `helperStyle` instead. But backticks are not references as far as the IDEs are concerned, so it means that if we rename a symbol in the IDE, then we miss anything that was a "local" reference to the symbol in the documentation, and we have to manually fix those up.
If Dartdoc would simply not render a local reference to the same symbol as a link (and just render it as code), then we could convert all the cases of using backticks to highlight local symbols into proper symbol references, and renaming would get a lot easier/less error prone.
The same is true for arguments to a function. For constructors, this is often not a problem, because linking to [argument] usually winds up linking to a property with the same name, but for regular functions, the IDE considers [argument] to be a link to the argument, but dartdoc will fail if you do that, because it doesn't consider it a symbol that can be linked (it doesn't have a page for each argument, understandably). So, ideally, bracketed references to arguments would be allowed, but if the symbol being documented is not a constructor, or it is, but there's no corresponding property, they simply get rendered as a backtick would. Then, in an IDE renaming of the argument will automatically fix the docs up, even if there's no actual link rendered in the dartdoc output. It could error out if there were no symbol or argument with that name (instead of just looking for a symbol).
This issue has led to style guide recommendations (so that we have correctness) that make renaming symbols more error prone. If dartdoc were to render these in the above ways, we could just say "link symbol and parameter names with brackets", which would also simplify the style guide. EDIT: Actually not true: I was mangling those recommendations in my head.
Activity
[-]Links to the same symbol should not be links[/-][+]Links to the same symbol should not be rendered as links[/+]srawlins commentedon Sep 9, 2022
I'm in favor of this for general UX, but I have some questions:
What is incorrect about a link that routes to the current page?
Why shouldn't this be done, regardless of dartdoc's priorities?
I read the link but cannot find what you're referring to, as far as self-referential references. There's a bit about parameters, unrelated.
gspencergoog commentedon Sep 9, 2022
It appears to be a no-op from the user's perspective (it causes a "hey, why didn't that link take me anywhere?" moment), and by being a link, it implies that there is more information to be found, but really, they've already found it.
Because it results in the above confusion.
Well, I was referring to that parameter text, which highlights the other issue that it's ambiguous to link a parameter (I wasn't attempting to address that here, although it is somewhat related). I was mainly referring to the recommendation to use backticks for parameters. I guess you're right that it's not really directly related to this issue, since it probably would continue to be the recommendation without a resolution to #1486
srawlins commentedon Sep 9, 2022
FWIW, this amazes me a little bit. There are two choices, right?
The Flutter team has decided that the latter option is the lesser of two evils?
srawlins commentedon Sep 9, 2022
To fix this, given a class instance method
mwith dartdoc text like/// [m] returns something really exciting., we want to either conditionally parse the text as a link:[m]as a link.m, we do not want to render[m]as a link.Which I think would be very hard to do. Or just always do the second thing, and not create a link for self-referential references. The UX there isn't that bad. I don't think there are more complicated cases than what I've listed above.
gspencergoog commentedon Sep 9, 2022
Apparently so. I wasn't part of that decision, so I'm not quite sure what all of the considerations were. It probably had something to do with the confusion between links to parameters and links to members in constructor documentation. Maybe @Hixie can comment.
Part of the reason I filed this was because I wanted to reverse that, but wanted to make it more of a no brainer by eliminating the confusion that self-linking links might cause.
Couldn't you just skip emitting links when generating the HTML if the link matches the current page's URL and write a
<code>section instead? Of course, I say that glibly without a clue about what the details of generating the HTML in Dartdoc are.srawlins commentedon Sep 9, 2022
Yeah this would be the best case scenario.
The code that parses a string of Markdown text is unconnected to the HTML file(s) where it will be written to.
gspencergoog commentedon Sep 9, 2022
Actually, it does say why in the style guide: "We want to avoid cases where a parameter that happens to be named the same as a property despite having no relationship to that property gets linked to the property."
Hixie commentedon Sep 9, 2022
My intent was that we would use square brackets, not backticks, for self-references. I'm not particularly worried about self-links being confusing, though I don't have an objection to dartdoc noticing they are redundant self-links and rendering them as non-links. The benefits of being consistent far outweigh anything else going on here.
Parameters are a special case. Dartdoc is ambiguous in its handling of
[...]in the presence of parameters with names that conflict with members. It's much more important to be able to link to members than parameters (there's nothing for the parameters to even link to), and in many cases in Flutter parameters correspond to identically-named members which we actually do want to link to. As a result, Flutter is supposed to use the convention that[...]does not refer to parameters.As with any project with hundreds of contributors, I'm sure we've made mistakes in practice, but the above is what I intended the style guide to say.
gspencergoog commentedon Sep 9, 2022
I (and maybe others) have often referred to the member itself with backticks inside of its own documentation, since otherwise it self-links to the page it's already on. (So, in the case at the top of this issue, I would use
`helperStyle`to avoid this).It seems like I may have incorrectly expanded the intent of the style guide in that case, since that doesn't appear to be the point of the rule in the style guide at all. As penance, I'll go find all the places I did that and fix them. :-)
If it's just too hard to implement prevention of the self-linking in dartdoc, then I guess just close this issue, and I'll not worry about it anymore.
Hixie commentedon Sep 10, 2022
I agree that self-references are mildly confusing. I think the inconsistency of sometimes using
[]and sometimes using`is even more confusing though, and we can't consistently use`because of templates. (Also, it makes copy and paste harder. Also, it means we don't get static analysis. But of course that's why you filed this bug. :-) )