automatically hyperlink references to top-level declarations #324
Conversation
|
Yeah, shippit. |
| def self.names_and_urls(docs) | ||
| names_and_urls = docs.flat_map do |doc| | ||
| # FIXME: autolink more than just top-level items. | ||
| [{:name => doc.name, :url => doc.url}] # + names_and_urls(doc.children) |
There was a problem hiding this comment.
why flat_mapping to a single-item array?
|
We might want to apply a more toned-down style to auto links as compared to normal links? |
|
What's the performance hit on this? I can imagine it could get to be quite large... |
Maybe by doing the auto linking at an earlier stage, where we can only apply it to the sections of text we want to? |
In practice, building the Xcode project takes the vast majority of the running time, so optimizing this is unlikely to have a large impact on overall run time for most projects. That being said, if you see obvious perf improvements that could be made, I'm all ears.
This wouldn't help. Consider the following scenario: public class MyClass {}
/**
This is my function.
This is a code sample that references MyClass.
*/
public func myFunc() {}We pass the whole comment to be parsed as Markdown. We can't reliably know where the code blocks are until the Markdown is parsed, and then afterwards we could avoid autolinking references enclosed within |
The best way I can think of to do this would be to strip all URLs out of code blocks as part of |
| end | ||
|
|
||
| def self.autolink(docs, data) | ||
| docs.map do |doc| |
There was a problem hiding this comment.
I don't think so. The intent is to return an array of transformed elements, not to mutate the elements in-place. So if this is what map is doing (passing mutable references to the elements), then making a copy of the doc block argument would be more "pure", but functionally the same I believe.
Good idea. What do you think of a new CSS style that only applies the blue link color on hover? |
automatically hyperlink references to top-level declarations
This dead simple implementation goes a pretty long way, but there are a few cases that could be improved:
Nevertheless, I don' think these limitations are enough to prevent adding this functionality. /cc @segiddins @orta.