document Quill's internals

zio / zio-quill

Compile-time Language Integrated Queries for Scala

https://zio.dev/zio-quill

Apache License 2.0

2.14k stars 346 forks source link

document Quill's internals #235

Open fwbrasil opened 8 years ago

fwbrasil commented 8 years ago

It'll make it easier to contribute to Quill.

gustavoamigo commented 8 years ago

Here are the things that I had a hard time so for:

Understanding what is done during compilation time and during runtime (or both)
How to debug queries
How to debug macros
Understanding the quotation parsing
Understanding how transformations are done using StatefulTransformer and StatelesTransformer
Understanding the AST produced before and after normalization
Understanding what is BetaReduction, maybe a better name would help
I still don't know what the (implicit r: WeakTypeTag[R], s: WeakTypeTag[S], t: WeakTypeTag[T]) in SourceMacro.scala are used for

Also, since Quill uses some quite advanced techniques, a study guide might be very useful.

mxl commented 7 years ago

I'm trying to fix bugs I found and it's very hard without documented internals.

fwbrasil commented 7 years ago

@mxl yeah, it's hard to get started without docs. I could give you pointers on how to fix specific issues, please comment on the issue or reach out to me on gitter if you'd like.

mslinn commented 6 years ago

As a Quill user I agree with @gustavoamigo's issues. Let's distinguish between documenting Quill internals and 'how to work effectively with Quill'. The issues @gustavoamigo raises fall into the latter category. I propose splitting this issue into three separate issues:

Document how to work effectively with Quill, specifically everything in @gustavoamigo's list
Document Quill internals (how the items in @gustavoamigo's list are implemented)
Study guide for those who would like to learn the theory involved behind the above