the way markdown links are written in the dart docs is not recognized by many markdown parsers

[kasperpeulen]

Many markdown links in the dartdocs are written in the following way:
[Node.textContent] (https://developer.mozilla.org/en-US/docs/Web/API/Node.textContent)

Node the space between [...] and (...). Writing links in this way is not regocnized by many markdown parsers:
http://johnmacfarlane.net/babelmark2/?normalize=1&text=%5BNode.textContent%5D+(https%3A%2F%2Fdeveloper.mozilla.org%2Fen-US%2Fdocs%2FWeb%2FAPI%2FNode.textContent)

It would be easier for developers if they don't have to write custom markdown rules to parse those links. For example, I'm using the marked-element from polymer 1.0:
https://elements.polymer-project.org/elements/marked-element
and this markdown parser doesn't recognise the dartdocs links.

[sethladd]

cc @alan-knight is this something we can change? I'm not sure how the MDN links get into the HTML docs in the first place.

[floitschG]

I think this would be a good idea. Currently it's also a pain to say provide a comment on a link in a comment. For example Goes from [x] (inclusive) to [y] (exclusive) because it is recognized as link.
Not allowing spaces (to be recognized as link) would make this possible.

[sethladd]

The new dartdoc will not convert [x] (inclusive) into a link.

[srawlins]

The sister markdown bug, dart-lang/markdown#53 was fixed in dart-lang/markdown#54.

[sethladd]

Thanks! The new dartdoc doesn't support [...] (...) (with a space)

[kasperpeulen]

@sethladd Wait, this issue was not about what dartdoc generator supports, but how the dart docs are written (in the sdk).

I still see a space in the markdown generated by Webstorm:

If I try to get the dartdocs by dart services, I don't get a space but a new line (\n) between [...] and (...), see:
https://dartpad.dartlang.org/f95a08039c19283baed3

If I would paste these dartdocs to for example common mark, then it still doesn't recognize the link:

[sethladd]

Ah, thanks for the clarification. Yes, we need to fix all the comments in our docs, to generate correct markdown links.

cc @alan-knight @terrylucas what are we using to generate the HTML libraries? Is there a place we can fix how the links are generated?

[srawlins]

Here's a fix for all of the [...] (...)-style non-links that are not in dart:html: https://codereview.chromium.org/1401063004

Note: This fix is important before the dartdoc package bumps the markdown package above 0.8.0.

There were too many in dart:html for me to go after yet. And apparently that stuff is generated?

[kevmoo]

Here's the full delta which includes this issue – kevmoo/dartdoc@42a7fa2?diff=split

[srawlins]

Second patch: https://codereview.chromium.org/1437773003/ in addition to the patch above that I list: https://codereview.chromium.org/1401063004

[srawlins]

Ping.

cc @alan-knight @terrylucas what are we using to generate the HTML libraries? Is there a place we can fix how the links are generated?

[alan-knight]

Oh, I was wondering why this markdown issue kept popping up to the top level inbox and wouldn't go away :-)

Those comments are generated out of the docs.json file, which has been passed down to us through the generations. It was once generated from somewhere else, or combined with data from elsewhere, but I'm pretty sure that if you edit them in there that will get propogated into html_dartium.dart and html_dart2js.dart

It's also a question as to whether those links are actually still valid. But they aren't obviously all broken, so it's probably not too bad.

[srawlins]

Thanks so much @alan-knight !!

Updated docs.json by hand and then generated the new Dart files. CL mailed. https://codereview.chromium.org/1440183003/

[srawlins]

OK last change log in the mail: https://codereview.chromium.org/1448963002/ which is the last needed to close this issue.

[srawlins]

OK this should be complete as of that last CL.

[kasperpeulen]

thanks for fixing this @srawlins