-
-
Notifications
You must be signed in to change notification settings - Fork 149
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[all][docs] Problems in documentation test repo #174
Comments
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 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:
Finally (for now), all changes to doc strings MUST be done on the develop branch... |
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 |
Thanks, @gavinpc-mindgrub - just fixed this earlier today, have updated the docs repo and now merged that branch back into |
The translation of anchor links in injectTOC seems to differ from the auto-generated markdown header anchor links in both Github and API Extractor.
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? |
- hard to find definitive info about GH's slugify rules - new rules based on more manual experiments and studying of unicode charts - likely not a watertight solution, but should fix most issues of prev impl
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 Ps. thank you so much for becoming a sponsor of this project! 🙏🙏 |
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!
The text was updated successfully, but these errors were encountered: