Documentation

[nex3]

What would you want to propose?

@csstools/css-tokenizer and @csstools/css-parser-algorithms fill a very useful need as standards-compliant and actively-maintained value-level CSS parsers. However, the lack of documentation stands as a major barrier to actually using this library. Beyond the README, there's no textual documentation at all either in the repo, on a website, or in the source code.

Suggested solution

Write function- and type-level documentation and, ideally, render it with a tool like TypeDoc and publish it online.

Additional context

No response

Validations

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Would you like to open a PR for this feature?

• I'm willing to open a PR

[romainmenke]

@nex3,

Thank you for calling this out.

I've been looking at api-extractor to resolve some typing issues.

This tool also seems to be able to generate docs, so that might be something we can add relatively easy.

---

Can you share what you are working on?
Always curious how this is used :)

[nex3]

We have an internal tool at Google that essentially polyfills certain CSS variables so that they're resolved just before the CSS is served instead of being shipped to the browser. This involves some moderately advanced CSS value transformations, as you might imagine. We've been using postcss-value-parser for this historically, but the spec-non-compliance and lack of maintenance is starting to catch up to us so we're looking for other alternatives.

[romainmenke]

• added and configured @microsoft/api-documenter
• documented @csstools/css-tokenizer
• documented @csstools/css-parser-algorithms

[romainmenke]

Hi @nex3,

We now have a system to generate and expose docs with @microsoft/api-documenter and I've written a decent chunk of both text docs and examples.

Going to close this because we now (technically) have documentation.

I am sure there will be follow up questions, but I don't want to keep writing more docs in a vacuum :)
Please open new issues if you have specific questions or if there are gaps.