Autolink improvements

[pcantrell]

This PR allows auto-links to siblings, ancestors, top-level elements, and dot-separated chains starting with any of the above:

It allows a (...) for long parameter lists, and per the original implementation, does not link from an element to itself:

It only links single-backticked text — nothing inside code blocks, nothing inside plain text. Here, “Configuration” happens to be the name of a struct in this project, but is used here as a plain English word in a situation where linking to the struct would be downright misleading:

As with previous changes to the generated docs, I’ll gather any feedback on the implementation first, then update integration specs. And changelog!

Fixes #328.

[jverkoey]

w00 this looks rad :)

[pcantrell]

Siesta docs are live with this now, so you can actually play with it and see how it feels. Here’s a couple of examples that show the various features in action:

https://bustoutsolutions.github.io/siesta/api/Classes/Resource.html#/s:vC6Siesta8Resource10latestDataGSqVS_6Entity_

https://bustoutsolutions.github.io/siesta/api/Structs/Configuration.html

[jpsim]

I don't think this does what you think it does. Here's the diff for Alamofire's docs from the integration specs:

[pcantrell]

“You keep using that code.”

Looks like I broke something in the midst of cleanup. Investigating.

[pcantrell]

Yeah, that was my dumb. Try it now.

[jpsim]

Ah, much better! I think we'd want to continue autolinking top-level Objective-C types that aren't backticked though, since the traditional three letter prefix should be enough to disambiguate from referencing a word vs the type.

[pcantrell]

Do you think so? The inconsistency of that seems confusing to me — though I do agree that the prefixes providing better uniqueness.

Others want to weigh in?

[jpsim]

It'd be nice to match Objective-C square bracket syntax too: [RLMRealm defaultRealm], +[RLMRealm defaultRealm] and -[RLMRealm writeCopyToPath:encryptionKey:error:].

[jpsim]

Freezing the children breaks reject_objc_enum_typedefs:

ROOT/lib/jazzy/sourcekitten.rb:468:in `reject!': can't modify frozen Array (RuntimeError)
    from ROOT/lib/jazzy/sourcekitten.rb:468:in `block in reject_objc_enum_typedefs'
    from ROOT/lib/jazzy/sourcekitten.rb:467:in `map'
    from ROOT/lib/jazzy/sourcekitten.rb:467:in `reject_objc_enum_typedefs'
    from ROOT/lib/jazzy/sourcekitten.rb:485:in `parse'
    from ROOT/lib/jazzy/doc_builder.rb:110:in `build_docs_for_sourcekitten_output'
    from ROOT/lib/jazzy/doc_builder.rb:68:in `build'
    from ROOT/bin/jazzy:15:in `<main>'

[jpsim]

This autolinking approach no longer links Results<T>, which is arguably a bad way to refer to a generic type anyway, but many will surely write it like that anyway.

[pcantrell]

Good points — I hadn’t even considered Obj-C support. Mostly because there was none when I started this PR!

The PR has its fingers in a lot of places, mostly because of the new parent-children relationship and associated refactoring. Having just dragged two long-running PRs along with many changes made underfoot, I propose breaking the remaining work into two separate pieces:

Before merging this PR: fix breakages, finish Swift work

• Fix reject_objc_enum_typedefs trying to mutate children.
• Fix generics in type name (Results<T>)
• Specs, docs, changelog

After merging this PR: normalize Obj-C support

• Add support for Obj-C bracket syntax
• Consider dropping support for dot syntax to refer to Obj-C items
• Haggle over whether Obj-C should detect class names without backticks

Sound good? I’m happy to keep working on it; I just want to get a merge in there sooner this time.

[jpsim]

Ah yes, probably smart to keep this PR from feature creeping. I agree with the 3 items you've listed that need to be done in this PR:

• Fix reject_objc_enum_typedefs trying to mutate children.
• Fix generics in type name (Results<T>)
• Specs, docs, changelog

As for the 3 points after this PR, I think it's fine to keep dot syntax for ObjC and that it's unnecessarily complicated to support ObjC type references without backticks, so really it's just supporting ObjC-style references like [RLMRealm defaultRealm], +[RLMRealm defaultRealm] and -[RLMRealm writeCopyToPath:encryptionKey:error:] and RLMRealm.configuration (which we already get).

[pcantrell]

Think I’ve fixed the outstanding issues.

My generic type handling is pretty hokey / permissive: I just strip out anything in angle braces, with no regard for whether it’s actually a generic type, what’s inside the braces, or even for brace balancing. My code thus autolinks to Array if given Array<Too,Many,Types>, Array<T>>>, or even Array<$@^∆˚™¢#%>. I think that’s probably just fine.

Will pick up specs, docs & changelog tomorrow.

[jpsim]

I think that’s probably just fine.

Agreed.

[pcantrell]

Current README seems too high-level to document this, so I just made notes in changelog. Current practice is not to link to this PR because it’s not an issue, correct?

[jpsim]

Current README seems too high-level to document this, so I just made notes in changelog. Current practice is not to link to this PR because it’s not an issue, correct?

Correct.

[pcantrell]

Think it’s GTG if CI passes.

[jpsim]

Looking at the specs diff, many of the nice places where autolink previously correctly picked up a link are now lost due to the new requirement that links be explicitly backticked, although many false positives are now addressed.

Overall, I consider this PR a major improvement, but one area where it would still be nice to have autolinking without requiring backticks is in "see", like @see RLMProperty/- see: Object.primaryKey(). It might make sense to add that in another PR though since I really do think it's an overall improvement as-is.

[pcantrell]

Agreed with all that. I do think people would start using the backticks if they become significant, but see: might be a good special case to handle. I’d even consider autolinking any of the special list items. (I use SeeAlso: a lot in the Siesta docs, but currently always backtick it.)

[jpsim]

I’d even consider autolinking any of the special list items.

My thoughts exactly. Anyway, 👍 for this PR. Merge at will, captain!

[pcantrell]

Another one down! Thanks for the fast turnaround on the questions.

[jpsim]

Hey, you did all the hard work! 👏

[nrudnyk]

@pcantrell Hello, can you share how you achieved reference for NSObject here https://bustoutsolutions.github.io/siesta/api/Classes/Resource.html#/s:vC6Siesta8Resource10latestDataGSqVS_6Entity ?? I'm generating docs for obj-c framework and wondering how to do the same. Thanks