[all][docs] Problems in documentation test repo

[postspectacular]

This temporary documentation repo is meant for testing out the new doc toolchain to provide better cross-package navigation and a (hopefully) generally improved experience... This doc repo consist of over 8000 markdown files and I cannot check them all myself for issues (of which there are still many...)

So this issue here is used to collect a list of links/pages exhibiting serious formatting problems. If you come across any eye sores, please do paste the offending URL as comment (and optionally / if needed, with a brief description). Thanks v.much in advance!

[postspectacular]

Just some more info about this:

TSDoc, the new syntax used for doc strings, is quite strict about the overall structure and furthermore currently still has issues with various markdown constructs in the comments, even though there're supported in principle.

The basic overall structure should at some point look something like:

/**
 * One or two sentences as top-level summary.
 *
 * @remarks
 * Longer comments / details here, possibly multiple paragraphs...
 *
 * @example
 * ```ts
 * // code example
 * const foo = () => 42;
 * ```
 *
 * @param a - foo bar
 * @param b - yada
 *
 * @public (or @alpha, @beta, @internal)
 */

More details about allowed & supported tags are here: https://api-extractor.com/pages/tsdoc/doc_comment_syntax/

Most of the current breakage is down to the majority of doc strings not using this above convention/structure and the combination of lack of @remarks tags and presence of code examples is breaking the resulting markdown (at least in the pacakge overview files (e.g. thi.ng/vectors).

The other current issue is with ambiguous link targets, i.e. links to overloaded functions, where each version is assigned its own unique reference. However, there's some discrepancy between documented behavior and actual formats used and I couldn't get this to work thus far. Also, this part of the TSDoc spec isn't finalized yet and so we might just delay trying to fix this until the spec & implementation in the doc generator is ready...

More info about that here:

• https://api-extractor.com/pages/tsdoc/declaration_references/
• [api-documenter] Fix ae-ambiguous-ids meta issue microsoft/rushstack#1308
• https://github.com/microsoft/tsdoc/blob/master/tsdoc/src/beta/DeclarationReference.grammarkdown

Finally (for now), all changes to doc strings MUST be done on the develop branch...

[postspectacular]

adding just for future reference:

• [api-extractor] classify arrow functions as functions microsoft/rushstack#1629
• [api-documenter] Fix ae-ambiguous-ids meta issue microsoft/rushstack#1308 (comment)

[GavinRay97]

This one has the formatting issue with pipe characters displaying from the example above:

https://github.com/thi-ng/umbrella-docs-temp/blob/master/transducers.md

[postspectacular]

Thanks, @gavinpc-mindgrub - just fixed this earlier today, have updated the docs repo and now merged that branch back into develop as well...

[chancyk]

The translation of anchor links in injectTOC seems to differ from the auto-generated markdown header anchor links in both Github and API Extractor.

• Github and API Extractor are both ignoring colons and commas instead of converting to hyphens (as in slugifyGH).
• Github and API Extractor both convert a "/" to a hyphen.
• API Extractor is converting & to "amp" instead of a hyphen.
• Github is converting & to a hyphen.

See the minimal example links under the hdom package for an example. I was attempting to fix this when I realized Github and API Extractor differ. Changing the behavior for colons and commas would be a partial fix, and then "&" could be avoided in heading links. Was there another system being supported with the colon and comma conversion to hyphens?

[postspectacular]

Happy new year @chancyk & thanks for looking into this more! I vaguely remember @nkint having pointed out issues with those generate slugs, but can't find the issue anymore 🤷‍♂️... I've just updated the slugifyGH() replacement rules after doing more manual experiments and checking unicode charts (see above commit)... As you can see I also re-generated all 140+ readmes and doing some spot testing seems they're all working now. Please do let me know if you still find any remaining offenders! :)

Ps. thank you so much for becoming a sponsor of this project! 🙏🙏