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

list.c: improve documentation about initializing binary semaphores

Author: ElectricRCAircraftGuy

list.c

@@ -184,15 +184,24 @@ void vListInsert( List_t * const pxList,
         *   4) Using a queue or semaphore before it has been initialised or
         *      before the scheduler has been started (are interrupts firing
         *      before vTaskStartScheduler() has been called?).
-        *   5) If the FreeRTOS port supports interrupt nesting then ensure that
+        *   5) Attempting to 'take' binary semaphores created using
+        *      `xSemaphoreCreateBinary()` or `xSemaphoreCreateBinaryStatic()`
+        *      APIs, before 'giving' them. Binary semaphores created using
+        *      `xSemaphoreCreateBinary()` or `xSemaphoreCreateBinaryStatic()`,
+        *      are created in a state such that the semaphore must first be
+        *      'given' using xSemaphoreGive() API before it can be 'taken' using
+        *      xSemaphoreTake() API.
+        *   6) If the FreeRTOS port supports interrupt nesting then ensure that
         *      the priority of the tick interrupt is at or below
         *      configMAX_SYSCALL_INTERRUPT_PRIORITY.
         **********************************************************************/
 
         for( pxIterator = ( ListItem_t * ) &( pxList->xListEnd ); pxIterator->pxNext->xItemValue <= xValueOfInsertion; pxIterator = pxIterator->pxNext )
         {
             /* There is nothing to do here, just iterating to the wanted
-             * insertion position. */
+             * insertion position.
+             * IF YOU FIND YOUR CODE STUCK HERE, SEE THE NOTE JUST ABOVE.
+             */
         }
     }