feat: support `@yields` and `@throws` tag blocks

[cmorten]

Fixes #225 Fixes #151

Adds the following to syntax highlighted JSDoc tag blocks:

• @returns
• @yields
• @yield
• @throws
• @exception

See https://doc-website-m9hog6kqk-denoland.vercel.app for testing, e.g. https://doc-website-m9hog6kqk-denoland.vercel.app/https/raw.githubusercontent.com%2Fdenoland%2Fdeno_std%2F0fc3b2e75e73892a8f4310798584bf052ba34dd0%2Fhttp%2Fserver.ts.

[CLAassistant]

All committers have signed the CLA.

[grian32]

While variants like @returns and @yields are technically valid JSDoc, I personally don't really agree with them as they cause discussion over something that doesn't matter all that much(basically the argument for no-config, which while I disagree with it for formatters and stuff I think it makes sense here)

[kitsonk]

Personally, I think we should avoid supporting JSDoc that doesn't impact how TypeScript analyses the types. Specifically there is a @yields request open and if you read the issue, it is rather complex, because there are several interfaces that could be applied to a @yields value that are totally ambiguous with that tag.

[cmorten]

While variants like @returns and @yields are technically valid JSDoc, I personally don't really agree with them as they cause discussion over something that doesn't matter all that much(basically the argument for no-config, which while I disagree with it for formatters and stuff I think it makes sense here)

I guess it depends on what we deem the purpose / value of the docs website? Afaik it is a useful utility to allow Deno module authors to have out of the box documentation for their module, not in itself a style guide or formatter. Abusing Postel’s law somewhat, I’m all for being strict in the deno fmt and lint builtins but here I feel it makes sense to have elegant documentation for users that have chosen to make use of a greater set of jsdocs given we give the impression of supporting them (another opportunity perhaps to reduce friction for Node authors contemplating supporting Deno?).

If folks are to start relying on this docs as a source of truth it is an omission to not document the likes of what can be thrown (whereas including immediately guides your error handling behaviour)? @kitsonk happy to concede on yield due to complexities raised in https://github.com/Microsoft/TypeScript/issues/23857 and https://github.com/gajus/eslint-plugin-jsdoc/pull/355, what are your thoughts on throw? I guess it can be documented as part of the description body, but feel would be nice to support despite having no ts benefits - the benefits come from transparency in documenting the non-golden path.

It is also curious that we support the alias @return but not the main form @returns - if we want to be opinionated with a subset of jsdocs then that is fine, so long as we are content with it not supporting a proportion of new/existing modules. Regardless it perhaps makes sense to document exactly what is supported (if not already) for clarity with users so they can easily integrate. Perhaps a small addition to the doc homepage?

R.E. @return vs plural - if we insist on supporting the prior, we should try to be self consistent with that in the manual and other locations e.g. https://deno.land/manual/tools/documentation_generator#documentation-generator

[kitsonk]

But where do you draw the line? JSDoc list 67 block tags and then there are the other variations of non-standard ones.

[cmorten]

Yeah get your point - it would be good to define the exact set desired, and then document that so it is transparent to users 😄 currently you might assume it fully supports JSDocs (indeed the likes of https://deno.land/manual/tools/documentation_generator#documentation-generator both has an unsupported @returns tag and perhaps implies that JSDocs are supported) which it doesn’t.

This is a separate issue(s) though, so will close this and raise something to that effect.

[cmorten]

Raised https://github.com/denoland/doc_website/issues/228