red-arch-doc-comments.md

My comments are in quotes like this one.

Red ORM

I think title must reflect the subject somehow. Perhaps, include the "architechture" word.

Red is a ORM for Raku that tries to mimic Raku's Seq's API but to query databases.

Since the document is aiming at potential contributors, this sentense is redundant. They already know its ORM, its about DBs. The only useful part of it is about Seq mimicing.

For doing that Red implements a custom Metamodel based on Metamodel::ClassHOW. To use that, you can use

Stylistical: "To use ... can use" – duplication. Could be something like (we're referring to the metamodel):

It backs the model keyword which could be used to declare a table and its relations as it's normally done to a Raku class.

the model keyword to describe your table and it's relations as a Raku class.

The Red Metamodel exports a meta-method called all or rs, which returns an instance of a class called Red::ResultSeq. Red::ResultSeq is essentially a specialization of Raku’s Seq type for data is on the database. So

MyModel.^all

represents all rows on the MyModel table, and

MyModel.^all.grep: *.col1 > 3

represents all rows on the MyModel table where the value of col1 is higher than 3. The grep method (and most of the other Red::ResultSeq methods) returns a new ResultSeq.

A ResultSeq stores a Red::AST tree and each method that returns a new Red::ResultSeq

It's not clear how does it store, how to access it. But primarily – what's the purpose of the AST and how ResultSeq uses it.

created this new Red::ResultSeq adding some more Red::AST.

It feels like there was an edit at this point which broke the sentense.

For example, the .map method runs the Callable code passing a the model's object type as the only parameter for that Callable. It has some logic to convert what the Callable does to Red::AST and creates a new Red::ResultSeq combining the Red::AST from the previous one with the one generated by the .map. (it's planned to change as soon as it's possible to create custom compile passes with RakuAST)

Once Red::ResultSeq is iterated, it uses the current Red::Driver to 2 things:

1. translate the Red::AST tree to SQL accordingly to the database variant (each Red::AST has it's own translation)
2. connect to the database and run the query

Once the database responds, it gets the response and returns a Seq with an object for each row.

Overall, since it's about architechture, a schematic drawing of relations between participating objects might be useful. And more generic information about each class role would be valuable. Like: Red::AST is used for this, Red::Driver does that... What I do in such situations is set it all aside for a day or two and let it simmer in the head in the meantime. Perhaps re-read it. And then return with fresh ideas.

Otherwise I'm excited you started this! Good docs is what most certainly was always missing from Red!

Thank you very much!