Auto-linking HTML-escaped operators

[reitzig]

Say I have code like this:

indirect enum Expr {
	case .number(Int)

	/**
		- Seealso: `Expr.&(...)`
	*/
	case .and(Expr, Expr)

	static func &(lhs: Expr, rhs: Expr) -> Expr {
		return .and(lhs, rhs)
	}
}

How do I refer to & in a way that auto-links?

Neither & (locally), Expr.&, Expr.&(...), nor Expr.&(lhs:rhs:) work.

[johnfairh]

The most reliable way is, in this case, +(_:_:) or Expr.+(_:_:) -- the part after the period is the name that jazzy thinks the symbol has, as show in its doc page.

I also found that Expr.+(...) worked for me, the ... works as a sort of wildcard.

[reitzig]

Hm... did you also try it in the callout? I'm on v0.8.1, if that's relevant.

I'm looking at the generated doc right now, and there's no link. (Things are called by different names, but that shouldn't be a problem? My operator is &.)

[johnfairh]

You're right, '&' doesn't work -- it's coming in as & to a routine that is not expecting that :/

[reitzig]

Ahh, oh my! Editing the original post so it's immediately clear what the issue is.

Given that Swift allows Unicode identifiers, apparently some hardening has to happen.

[SDGGiesbrecht]

Does the flag --use-safe-filenames handle the ampersand? When it is turned on, Jazzy sanitizes any characters that are bad to use in URLs (the definition of which characters are “bad” is left up to Ruby).

[SDGGiesbrecht]

P.S. At least with --use-safe-filenames on, I can reliably link with things like ×(_:_:) and √(_:), so this is related to HTML, not Unicode.

[johnfairh]

That flag doesn't help here: the problem happens before generating the link, code is matching html-escaped text from markdown output against real declaration names. Yes general unicode is fine, it's just the html escapes & < > that cause problems AFAICT.

[SDGGiesbrecht]

I just verified it. @johnfairh, you are right on all counts. I stand corrected.

[johnfairh]

Fixed in master.