Document CodeBlock

[TheDoctor314]

This Pull Request fixes/closes #1609.

It changes the following:

• Adds CodeBlock docs

[Razican]

Hi @TheDoctor314! Thank you for your contribution :)

This indeed goes towards the good direction. I see a couple of missing things, though. First, the length attribute doesn't have correct documentation comments (// should be changed for ///). The params attribute is also missing documentation.

This PR, in order to fully solve #1609, should also add some documentation to all internal methods where it's missing, such as new() and instruction_operands(), and to the module-level too.

Furthermore, I would prefer if we could add some extra explanation, like a longer description below what is usually the short description (the first line). And, if we could have some # Safety documentation in the Readable trait this would be perfect :)

[codecov]

Codecov Report

Merging #1691 (81595ac) into main (da29677) will decrease coverage by 0.06%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1691      +/-   ##
==========================================
- Coverage   50.91%   50.85%   -0.07%     
==========================================
  Files         199      199              
  Lines       17707    17803      +96     
==========================================
+ Hits         9016     9053      +37     
- Misses       8691     8750      +59     

Impacted Files	Coverage Δ
boa/src/vm/code_block.rs	0.00% <ø> (ø)
boa/src/syntax/parser/function/mod.rs	49.65% <0.00%> (-12.15%)	⬇️
boa/src/syntax/ast/node/mod.rs	70.16% <0.00%> (-1.27%)	⬇️
...pression/primary/async_generator_expression/mod.rs	46.51% <0.00%> (-1.11%)	⬇️
...ser/expression/primary/generator_expression/mod.rs	43.90% <0.00%> (-1.10%)	⬇️
...arser/expression/primary/object_initializer/mod.rs	49.44% <0.00%> (-0.75%)	⬇️
boa/src/builtins/console/mod.rs	25.00% <0.00%> (-0.31%)	⬇️
...tax/parser/expression/assignment/arrow_function.rs	63.49% <0.00%> (+0.15%)	⬆️
boa/src/builtins/function/arguments.rs	85.71% <0.00%> (+0.25%)	⬆️
boa/src/object/internal_methods/function.rs	71.56% <0.00%> (+0.56%)	⬆️
... and 4 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update da29677...81595ac. Read the comment docs.

[TheDoctor314]

Thanks for the feedback!
I am not too familiar with unsafe code in general. What kind of safety argument should be made for the Readable trait?

[jasonwilliams]

Is this the length of arguments this function takes?

[jasonwilliams]

Maybe something like this at the top which says.

//! CodeBlock
//! This module is for the CodeBlock which implements a function representation in the VM

[jasonwilliams]

above

[jasonwilliams]

And, if we could have some # Safety documentation in the Readable trait this would be perfect :)

@HalidOdat are you able to help explain the need for unsafe readable here?
https://github.com/boa-dev/boa/blob/main/boa/src/vm/code_block.rs#L26-L35

[RageKnify]

LGTM but I think we might want to wait for @HalidOdat to say something about the documentation of the unsafe parts