Merge pull request #977 from jphickey/fix-545-taskcreate-doc

Fix #545, update OS_TaskCreate doc

src/os/inc/osapi-task.h

@@ -81,12 +81,22 @@ typedef osal_task((*osal_task_entry)(void)); /**< @brief For task entry point */
  * Creates a task and passes back the id of the task created. Task names must be unique;
  * if the name already exists this function fails. Names cannot be NULL.
  *
+ * Portable applications should always specify the actual stack size in the
+ * stack_size parameter, not 0.  This size value is not enforced/checked by OSAL,
+ * but is simply passed through to the RTOS for stack creation. Some RTOS
+ * implementations may assume 0 means a default stack size while others
+ * may actually create a task with no stack.
+ *
+ * Unlike stack_size, the stack_pointer is optional and can be specified as NULL.
+ * In that case, a stack of the requested size will be dynamically allocated from
+ * the system heap.
+ *
  * @param[out]  task_id will be set to the non-zero ID of the newly-created resource
  * @param[in]   task_name the name of the new resource to create
  * @param[in]   function_pointer the entry point of the new task
  * @param[in]   stack_pointer pointer to the stack for the task, or NULL
  *              to allocate a stack from the system memory heap
- * @param[in]   stack_size the size of the stack, or 0 to use a default stack size.
+ * @param[in]   stack_size the size of the stack
  * @param[in]   priority initial priority of the new task
  * @param[in]   flags initial options for the new task
  *