This is an excellent PR description and process. I'm looking forward to seeing this develop :)

Wow, GitHub actions can inline errors in the PR diff? Awesome!

While I don't think that we should merge this just yet, this PR is ready for an initial review pass.

I'm especially looking for feedback/ideas regarding the following:

• Does this format of documentation work well?
• Some functions are still rather long, should these be further split up? If yes, should this be done in this PR?
• The algo.rs file is too long for my taste (and it will get longer in the future). Should we move some of the functions to another file, e.g. in an algo module folder?
• Can you spot step 4 of the algorithm? I'm not sure if it's not implemented or just not documented explicitly.
• Does passing the constants through the AlgoConstants struct work well or should I pass each field separately to the functions?
• The benchmarks showed a performance regression of about 5%, but they seem to be quite noisy. Can you reproduce these results on your local machine? If yes, do you have any ideas on how to improve the performance?

Feel free to nitpick this PR, I think it's important that we create a good foundation here for future developments.

I did a quick pass and overall I like the direction of this PR. Adding actual links to the spec with the relevant section when it is mentioned is really nice. I also like passing the constants struct around.

I agree that the file is quite big, but after a quick review it's hard to tell what part could be extracted. I guess things like computing constants could be in a separate file.

I'm not familiar enough with what it does to confidently say it doesn't change any behavior though.

I wonder if it's possible to do some of that in a few separate PRs. Like for example, could you do a PR that focuses on improving the comments without doing anything else? This could help make it easier to review.

(for the record, I come from the bevy community)

Thank you for your feedback!

I thought that maybe the different "sections" of the flexbox specs could be in different files. But I'm not sure if it's good practice in Rust to split impl blocks up like that and some spec sections are also considerably bigger than others.

Separating the doc improvements and refactoring would be possible in theory, but the "new" comments are tailored to them being on a new function, it would be weird to add the section name to each comment when it's in a single function IMO.
I tried to keep actual code changes to a minimum, but you are right that it's not that easy to review. A potential solution would be to review by commit instead of all changes at once.
Another option would be to add unit tests to make sure that no functionality broke, now that we have everything in separate functions this would be feasible. But I'm not sure how easy it is to set up the proper conditions for each function and how long it would take. This would also make the PR even bigger.

I would really like unit tests for this, but in a follow-up PR. I'll do a pass on this in the coming week, commit-by-commit :)

• Can you spot step 4 of the algorithm? I'm not sure if it's not implemented or just not documented explicitly.

Is this code somehow responsible for a non-spec-abiding variant of step 4?

My code-comprehension isn't good enough to see if that is actually the case, but there are no other candidates I see that could be implementing step 4

Does this format of documentation work well?

Yes, this is better. It improves readability :)

• Can you spot step 4 of the algorithm? I'm not sure if it's not implemented or just not documented explicitly.

Is this code somehow responsible for a non-spec-abiding variant of step 4?

My code-comprehension isn't good enough to see if that is actually the case, but there are no other candidates I see that could be implementing step 4

It definitely might be, as step 4 is about Determine the main size of the flex container

@TimJentzsch this is failing due to two missing imports:

use crate::style::{Style, FlexDirection};

Github is hating me, so I can't easily make the changes myself. Once that's done this is ready to merge.

I'm on vacation right now but will get on that in a couple of days

Sounds good. I'll see what I can do on my own then :)

Merged as #88 :D