update comments

2 files changed, 84 insertions, 13 deletions

diff --git a/xmake/core/base/log.lua b/xmake/core/base/log.lua
index 405002286..7995c8b38 100644
--- a/xmake/core/base/log.lua
+++ b/xmake/core/base/log.lua
@@ -21,7 +21,10 @@
 -- define module: log
 local log = log or {}
 
--- get the log file
+-- get the log file object
+--
+-- @return      the file object
+--
 function log:file()
 
     -- disable?
@@ -56,7 +59,10 @@ function log:file()
     return self._FILE
 end
 
--- get the output file
+-- get the output log file path
+--
+-- @return      the log file path
+--
 function log:outputfile()
     if self._LOGFILE == nil then
         self._LOGFILE = os.getenv("XMAKE_LOGFILE") or false
@@ -64,19 +70,22 @@ function log:outputfile()
     return self._LOGFILE
 end
 
--- clear log
+-- clear the log file
 function log:clear(state)
     if os.isfile(self:outputfile()) then
         io.writefile(self:outputfile(), "")
     end
 end
 
--- enable log
+-- enable or disable logging
+--
+-- @param state  true to enable, false to disable
+--
 function log:enable(state)
     self._ENABLE = state
 end
 
--- flush log to file
+-- flush log buffer to file
 function log:flush()
     local file = self:file()
     if file then
@@ -92,7 +101,10 @@ function log:close()
     end
 end
 
--- print log to the log file
+-- print log with newline to the log file
+--
+-- @param ...   the format string and arguments
+--
 function log:print(...)
     local file = self:file()
     if file then
@@ -100,7 +112,10 @@ function log:print(...)
     end
 end
 
--- print variables to the log file
+-- print variables to the log file (verbose mode only)
+--
+-- @param ...   the variables to print
+--
 function log:printv(...)
     local file = self:file()
     if file then
@@ -120,7 +135,10 @@ function log:printv(...)
     end
 end
 
--- printf log to the log file
+-- printf log without newline to the log file
+--
+-- @param ...   the format string and arguments
+--
 function log:printf(...)
     local file = self:file()
     if file then
@@ -128,7 +146,10 @@ function log:printf(...)
     end
 end
 
--- write log the log file
+-- write raw data to the log file
+--
+-- @param ...   the data to write
+--
 function log:write(...)
     local file = self:file()
     if file then
diff --git a/xmake/core/base/scheduler.lua b/xmake/core/base/scheduler.lua
index 060ceb616..a59c38207 100644
--- a/xmake/core/base/scheduler.lua
+++ b/xmake/core/base/scheduler.lua
@@ -483,16 +483,33 @@ function scheduler:_profiler()
 end
 
 -- start a new coroutine task
+--
+-- @param cotask the coroutine task function
+-- @param ...    the task arguments
+-- @return       the coroutine object
+--
 function scheduler:co_start(cotask, ...)
     return self:co_start_named(nil, cotask, ...)
 end
 
 -- start a new named coroutine task
+--
+-- @param coname the coroutine name for debugging
+-- @param cotask the coroutine task function
+-- @param ...    the task arguments
+-- @return       the coroutine object
+--
 function scheduler:co_start_named(coname, cotask, ...)
     return self:co_start_withopt({name = coname}, cotask, ...)
 end
 
 -- start a new coroutine task with options
+--
+-- @param opt    the options, e.g. {name = "xxx", isolate = true}
+-- @param cotask the coroutine task function
+-- @param ...    the task arguments
+-- @return       the coroutine object
+--
 function scheduler:co_start_withopt(opt, cotask, ...)
 
     -- check coroutine task
@@ -543,6 +560,11 @@ function scheduler:co_start_withopt(opt, cotask, ...)
 end
 
 -- resume the given coroutine
+--
+-- @param co     the coroutine object
+-- @param ...    the resume arguments
+-- @return       true on success, and the yield results
+--
 function scheduler:co_resume(co, ...)
 
     -- do resume
@@ -570,6 +592,10 @@ function scheduler:co_resume(co, ...)
 end
 
 -- suspend the current coroutine
+--
+-- @param ...    the suspend results to return to resume caller
+-- @return       the resume arguments
+--
 function scheduler:co_suspend(...)
 
     -- suspend it
@@ -594,12 +620,15 @@ function scheduler:co_suspend(...)
     return table.unpack(results)
 end
 
--- yield the current coroutine
+-- yield the current coroutine (give up execution temporarily)
 function scheduler:co_yield()
     return scheduler.co_sleep(self, 1)
 end
 
--- sleep some times (ms)
+-- sleep the current coroutine for given milliseconds
+--
+-- @param ms     the sleep time in milliseconds
+--
 function scheduler:co_sleep(ms)
 
     -- we don't need to sleep
@@ -631,7 +660,10 @@ function scheduler:co_sleep(ms)
     return true
 end
 
--- lock the current coroutine
+-- lock the current coroutine (cooperative lock by name)
+--
+-- @param lockname   the lock name
+--
 function scheduler:co_lock(lockname)
 
     -- get the running coroutine
@@ -682,6 +714,9 @@ function scheduler:co_lock(lockname)
 end
 
 -- unlock the current coroutine
+--
+-- @param lockname   the lock name
+--
 function scheduler:co_unlock(lockname)
 
     -- get the running coroutine
@@ -713,6 +748,10 @@ function scheduler:co_unlock(lockname)
 end
 
 -- get the given coroutine group
+--
+-- @param name   the group name
+-- @return       the coroutines table in this group
+--
 function scheduler:co_group(name)
     return self._CO_GROUPS and self._CO_GROUPS[name]
 end
@@ -742,7 +781,12 @@ function scheduler:co_group_begin(name, scopefunc)
     return true
 end
 
--- wait for finishing the given coroutine group
+-- wait for finishing all coroutines in the given group
+--
+-- @param name   the group name
+-- @param opt    the options, e.g. {limit = 8}
+-- @return       true on success, or errors
+--
 function scheduler:co_group_wait(name, opt)
 
     -- get coroutine group
@@ -815,6 +859,9 @@ function scheduler:co_group_waitobjs(name)
 end
 
 -- get the current running coroutine
+--
+-- @return       the current coroutine object
+--
 function scheduler:co_running()
     if self._ENABLED then
         local running = coroutine.running()
@@ -823,6 +870,9 @@ function scheduler:co_running()
 end
 
 -- get all coroutine tasks
+--
+-- @return       the tasks table
+--
 function scheduler:co_tasks()
     local cotasks = self._CO_TASKS
     if not cotasks then