search

denoland / doc_website

Archived. New version at https://github.com/denoland/docland
https://doc.deno.land/
MIT License
194 stars 43 forks source link

docs: document supported JSDocs syntax #228

Open cmorten opened 3 years ago

cmorten commented 3 years ago

The doc website currently only supports a limited subset of JSDocs tags and syntax, and the vibe is that there is much desire to maintain a larger set of support (REF: https://github.com/denoland/doc_website/pull/226).

For transparency, could we consider adding the supported tags / syntax to the docs website (or manual) so it is clear to users what the docs website supports? Namely:

At the moment it is possible to misinterpret the likes of https://deno.land/manual@v1.13.2/tools/documentation_generator, which have examples using unsupported syntax (types) and tags (@returns), to then think https://doc.deno.land/ will also support this in it's generated documentation. Finding that it doesn't support some of the common JSDocs tags / syntax can be confusing for users as it is unclear whether there is an error in their JSDocs or if it is a limitation of the docs website itself - e.g. https://github.com/denoland/doc_website/issues/217

I’m not sure if this is an issue with the deno doc parser or with the html rendering done here...

This documentation could be added to the https://doc.deno.land/ homepage, or to the manual.

As an aside, in places where https://doc.deno.land/ is promoted, we should also consider writing examples to reflect the actual JSDocs support.

For prior art / precedent, see how TypeScript documents the subset of JSDoc that it supports https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html, and how TSDoc documents the subset of JSDoc that it supports https://tsdoc.org/ (e.g. doesn't support @return unlike https://doc.deno.land/, opting instead for @returns - REF: https://github.com/denoland/doc_website/issues/151).

grian32 commented 3 years ago

I’m not sure if this is an issue with the deno doc parser or with the html rendering done here...

I believe all deno doc does in regards with doc.deno.land is give it the JSDoc stripped of comments and *'s. I'll look into PRing support for @ignore tags.

cmorten commented 3 years ago

I’m not sure if this is an issue with the deno doc parser or with the html rendering done here...

I believe all deno doc does in regards with doc.deno.land is give it the JSDoc stripped of comments and *'s. I'll look into PRing support for @ignore tags.

Ah that was a quote from https://github.com/denoland/doc_website/issues/217 😅 but yes that sounds about right 😄