document public api and more

[aladdin-add]

• project arch
• public API
• config file (to do)
• cli (to do)
• how to contribute
• FAQ
• ...

[KFlash]

@aladdin-add Not sure if there is a point in mention this in the documentation, but Kataw threats keywords differently.
For example this case let for. In this case the for keyword isn't allowed to be part of the lexical declaration. Instead the loop breaks, and for will be parsed out as forStatement.

It's done like this because Kataw re-construct the AST in all scenarios when it does error recovery.

Note You also need to document whitespace and line terminators. I described it here:

https://github.com/kataw/kataw/blob/main/src/parser/README.md#whitespace-and-linebreak

[KFlash]

@aladdin-add friendly ping. You should mention in the documentation that Kataw can parse type annotations, but differently than TS and Flow. Need to do a 'in-depth' documentation for Kataw types.

[KFlash]

@aladdin-add
Need to mention in the documentation how to gain perf with Kataw CST nodes.

For example escaped keywords can be found in Acorn and Babel parser I guess if you are using the raw property

if (x !== x.raw) // escaped

In Kataw you can do:

if (kataw.hasUnicodeEscape(x) // escaped

You can narrow this down further because you know this kind of tokens doesn't have any children - escaped keyword

if (kataw.isChildLess(x) {
// check for escaped keywords
if (kataw.hasUnicodeEscape(x) // escaped
}

If you need all Statement nodes in Acorn and Babel parser:

switch (node.type) {
case 'IfStatement': ...

// and 100 more cases
}

In Kataw you can do:

if (kataw.isStatementNode(x) // true if statement node

There are many more examples

[KFlash]

@aladdin-add Close this? No progress last 4 months

[aladdin-add]

we'll have to document some of these before release v0.1.0

[KFlash]

Some of the .md files in various folder may give you some clues

[KFlash]

@aladdin-add Wait with the documentation. Kataw is undergoing a huge refactoring and I'm changing it to something I had zero plans to do :(

Soon as I'm done we need to document the folder structure first.