Skip to content

It's documentation time - #78

Open
AsterixxxGallier wants to merge 13 commits into
rj00a:mainfrom
AsterixxxGallier:main
Open

AsterixxxGallier wants to merge 13 commits into
rj00a:mainfrom
AsterixxxGallier:main

Conversation

@AsterixxxGallier

Copy link
Copy Markdown

I documented all over the place!

Specifically these modules:

  • access
  • archetype
  • bit_set
  • component
  • entities
  • event (and submodules)
  • fetch
  • handler
  • world

All public API was already documented, but not many internal functions. I added docs for most of them. I also added comments inside of some functions to explain their implementation. I added notes and TODOs whenever I saw something that I thought could be improved or optimized. However, apart from one test I added, the code itself was left untouched - no functionality changed, not even implementation details.

I hope this makes the codebase more navigable and understandable. I'm open to feedback, additions, changes and critique!

@giantcow giantcow left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't have a tonne of time to look through this, but put down a few comments

In general, I think some of the additions are useful to add context (especially for me coming in new to this project), but there are a significant number of internal comments (//) that are just stating what a single line is doing... I'd suggest avoiding those as they tend to just add bloat

Comment thread src/access.rs
Comment on lines +281 to +282
/// queried via the `archetype_has_component` function.
pub(crate) fn matches_archetype<F>(&self, mut archetype_has_component: F) -> bool

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mega-nit:

Suggested change
/// queried via the `archetype_has_component` function.
pub(crate) fn matches_archetype<F>(&self, mut archetype_has_component: F) -> bool
/// queried via the given function.
pub(crate) fn matches_archetype<F>(&self, mut does_archetype_have_component: F) -> bool

Comment thread src/archetype.rs
let empty = self.empty_mut();

let rellocated = unsafe { empty.reserve_one() };
// Reserve space for the spawned entity.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably have a // SAFETY comment

Comment thread src/archetype.rs
Comment on lines +175 to 176
// Remove the archetype.
let mut arch = self.archetypes.remove(arch_idx.0 as usize);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't think this comment is adding any value over the method name

Comment thread src/archetype.rs
Comment on lines +336 to +338
// The archetype already exists, insert it into the
// map and return it.
*vacant_insert_components.insert(*entry.get())

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't think this is comment is adding any value, it just restates how insert works

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants