Interlinking syntax & markdown

[tmcw]

documentation.js uses Markdown. rustdoc started markdown, switched, switched back to markdown.

• Markdown is super popular
• But we want to differentiate links that are meant to inter-link documentation versus those meant to link to the outside world, or to other parts of a website.
• JSDoc has its own link syntax, because afaik it predates Markdown.

Thoughtbubbles:

What if there was a protocol for interlinks, like

This is like [the stringify method](doc://JSON.stringify)

[jamiebuilds]

Yeah it'd be cool to have some kind of ref syntax which looks values up from scope:

import JSON from 'special-json-library';

/**
 * Description, uses [JSON.stringify](...)
 */

[jamiebuilds]

I think if we did that you could get away with not having much of a syntax:

import JSON from 'special-json-library';

/**
 * Automatically turns into a ref: [[JSON.stringify]]
 */

[ELLIOTTCABLE]

I've written on this elsewhere, but relating to my post on #9 — I'd really like to see “links” in source-code documentation devolve to their absolute minimum format. That is, whenever possible, I'd like every single identifier in the documentation-prose to deterministically, semantically, relate to its definition in the source-code.¹

To that end, I think the syntax should be absolutely as short as possible … and more importantly, not be different than the syntax for non-hyperlinked code spans², so that the user doesn't have to decide what is worth linking (i.e., the user can just assume the implementation will link everything, as long as it's simple enough.)

import JSON from 'special-json-library'

/**
 * This automatically turns into a reference to `JSON.stringify`; but something
 * that doesn't immediately reduce to a specific namepath, like `this.wont("and can't")`, doesn't.
 */

In fact, I've already been writing my documentation in this style for years.

Now, I don't think a documentation-generator needs to be parsing code-blocks and code-spans in the documentation, and resolving runtime references, or anything like that — but, thanks to #9, staticly-dereferencable “namepaths” are now indistinguishable from actual, JavaScript, source-code (except by their simplicity); and the best way to take advantage of that new homoiconic syntax is to simply remove the distinction between “code” and “named code” entirely, and heuristically determine it at runtime.

For situations in which this fails, for some reason or other, and you need to force the documentation-generator into generating a link … the traditional {@link <name>} syntax could be preserved (or one similar to it); but I don't feel there's any need to make that any shorter, if the vast majority of references can simply be `myClass` and (see `myClass.method`) and such.

Hope my wall-of-text contributions were welcome — obviously, source-code documentation syntax is a subject that I care deeply about! 🤣

---

1. To be clear, I'm not suggesting that every single instance be hyperlinked in the documentation — at generation-time, I think it's sufficient to take the Wikipedia approach, and only hyperlink the first occurrence:

   /**
    * This function takes a `Source`, and generates a list of associated `Source`s.
    * If the given `Source` is not ...

   ==>

   <p>This function takes a <a href="#t-Source"><code>Source</code></a>, and
   generates a list of associated <code>Sources</code>. If the given
   <code>Source</code> is not …</p>

2. That said, although I don't personally love it, I do understand that there may be cases where you're discussing two different types of code, and need to differentiate the “this is source-code” semantic expressed by `` ==> <code></code>, and a “this is source-code in our local language that should thus be resolved and linked by the doc-generator”. If you want to make that distinction, though, I strongly suggest that you still use only one character for it, so that it's useful pervasively, instead of once or twice per documentation-block:

   /**
    * This function takes a +Source+, and generates a list of associated +Source+s.
    * If the given +Source+ is passed with the special `--source` flag on the
    * command-line, or shows up in a `<elem data-source="...">` attribute ...

   Now, In my opinion, this is an unnecessary, and distracting, disambiguation. For the conflict to be a problem in practice, it'd have to cause name-resolution to the wrong thing, which means it would have to resolve at all, which would mean the “other language” in question has to look sufficiently-similar to JavaScript for the names to resolve in the first place … and I think the cases where you'll be writing snippets of two such sufficiently-similar languages in your JavaScript documentation are vanishingly rare (implementing other programming languages in JavaScript, as I myself spend a lot of my time doing, is probably the only realistic such case, actually!) If that's true, then punishing the general user of JSdoc by forcing them to learn, and remember, a separate syntax for auto-linked snippets of code, is folly, imho.

[ELLIOTTCABLE]

Probably obviously from the above, I'm also personally partial to implicit support for postfix-declensions, most especially the English plural — I find typing `Source`s much more natural than something horrific like [[`Sources`|Source]] or what-have-you; but I still want my documentation to read naturally, as <a href="#t-Source"><code>Sources</code></a>, not <a href="#t-Source"><code>Source</code></a>s or, god forbid, a broken link to <a href="#t-Sources"><code>Sources</code></a>.

Then again, I come from an old Wikipedia tradition, where we really like syntactic conveniences like that … :P

[jamiebuilds]

That is, whenever possible, I'd like every single identifier in the documentation-prose to deterministically, semantically, relate to its definition in the source-code.

I strongly disagree with this, you should be allowed to you Markdown's syntax for code wherever you want. Links should be marked as links.

[tmcw]

Now that we're aiming at a CommonMark superset, could we adopt the CommonMark 'verbatim reference link' syntax, like

/**
 * Automatically turns into a ref: [JSON.stringify]
 */

So conceptually, writing docs you think you're writing as if all of the namepaths available to link were already set as link reference definitions, so this would be kind of like

/**
 * Automatically turns into a ref: [JSON.stringify]
 *
 * [JSON.stringify]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
 */

This seems like a net win - the only corner I see is what if someone does put a literal link reference definition in the code comment like as in above - which seems legit and fine as a way to optionally override behavior.