Make it possible to embed images

[nikwen]

I tried to add an image to the description of a function like this:

![Alt](../images/image.png)

The docs-parser complained with this error:

docs-parser/src/markdown-helpers.ts

Lines 710 to 713 in 854a714

	expect(tokenToCheck.children).to.equal(
	null,
	'There should be no nested children in the joinable tokens',
	);

It would be great to not error out if there is an image in the function description.

In the TypeScript comments, we could just leave the original markdown of the image or convert it into just the image URL.

[nikwen]

I have worked around it by adding an <img> tag.

[dsanders11]

In the TypeScript comments, we could just leave the original markdown of the image or convert it into just the image URL.

I wonder if we should just swap in the alt text with some standardized text like "[Image: <alt-text>]". I don't think there's much value in leaving a raw image URL or Markdown since there's no way for the user seeing the comment in Intellisense to reasonably see the image, short of just going to the docs on our website.

[nikwen]

I like that format!

I have no super strong opinions on this, but I think it could be helpful to copy and open the image link from the IDE sometimes.

I also wonder if some IDEs (Jetbrains?) would actually render a Markdown image.

But in general, I'm more interested in not getting the error again than arguing over the exact format. So whatever someone chooses to implement, I'll be fine with it.

[dsanders11]

I have no super strong opinions on this, but I think it could be helpful to copy and open the image link from the IDE sometimes.

The main issue here is it's unclear what the image link should be, as the website doesn't have versioned URLs, and the image may be removed from the latest version of the docs, etc.

But in general, I'm more interested in not getting the error again than arguing over the exact format. So whatever someone chooses to implement, I'll be fine with it.

Yea, let's start with swapping in alt text and go from there.