list.c: improve code comments to point to official documentation about problems which may cause code to get stuck inside of list.c

ElectricRCAircraftGuy commented 1 month ago

Description

Improve comments to help people when debugging. This would have saved me weeks of time. An uninitialized binary semaphore (ie: one which has not been given yet) will result in getting stuck inside of vListInsert(). You must give it before taking it.

Test Steps

Create a semaphore, start the scheduler, try to take it. You'll get stuck in a debugger inside the for loop in VListInsert().

Now, right after creating it, but before starting the scheduler, give it. Start the scheduler. Now, when it is taken it works fine.

Checklist:

[ ] I have tested my changes. No regression in existing tests.
[ ] I have modified and/or added unit-tests to cover the code changes in this Pull Request.

Can someone please run necessary tests on your end to ensure this is behavior you see too?

Related Issue

NA

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

kstribrnAmzn commented 1 month ago

Hello @ElectricRCAircraftGuy! Thanks for submitting the PR. I like the idea of improving the documentation but I believe this case is well covered by both our website documentation and in the semaphore header. I'd like to leave the documentation there to keep a single authoritative source. Updating the list source code comment to point the authoritative documentation will ensure comments stay up to date with the behavior.

Please see my suggestions about how to rework the comment.