update more comments

2 files changed, 41 insertions, 3 deletions

diff --git a/xmake/core/project/policy.lua b/xmake/core/project/policy.lua
index 0cf184d91..617a792d6 100644
--- a/xmake/core/project/policy.lua
+++ b/xmake/core/project/policy.lua
@@ -30,6 +30,9 @@ local utils   = require("base/utils")
 local string  = require("base/string")
 
 -- get all defined policies
+--
+-- @return      the policies table {name = {description, ...}, ...}
+--
 function policy.policies()
     local policies = policy._POLICIES
     if not policies then
@@ -212,6 +215,10 @@ function policy.policies()
 end
 
 -- set policy default value
+--
+-- @param name  the policy name, e.g. "build.ccache"
+-- @param value the default value
+--
 function policy.set_default(name, value)
     local defined_policy = policy.policies()[name]
     if defined_policy then
@@ -221,7 +228,12 @@ function policy.set_default(name, value)
     end
 end
 
--- check policy value
+-- check and validate policy value
+--
+-- @param name  the policy name
+-- @param value the value to check
+-- @return      the validated value
+--
 function policy.check(name, value)
     local defined_policy = policy.policies()[name]
     if defined_policy then
diff --git a/xmake/core/project/rule.lua b/xmake/core/project/rule.lua
index c11c6e246..790f715fa 100644
--- a/xmake/core/project/rule.lua
+++ b/xmake/core/project/rule.lua
@@ -84,24 +84,42 @@ function _instance:clone()
     return instance
 end
 
--- get the rule info
+-- get the rule info value
+--
+-- @param name  the info name
+-- @return      the info value
+--
 function _instance:get(name)
     return self._INFO:get(name)
 end
 
 -- set the value to the rule info
+--
+-- @param name  the info name
+-- @param ...   the values
+--
 function _instance:set(name, ...)
     self._INFO:apival_set(name, ...)
     self:_invalidate(name)
 end
 
 -- add the value to the rule info
+--
+-- @param name  the info name
+-- @param ...   the values to add
+--
 function _instance:add(name, ...)
     self._INFO:apival_add(name, ...)
     self:_invalidate(name)
 end
 
 -- get the extra configuration
+--
+-- @param name  the config name
+-- @param item  the config item
+-- @param key   the config key (optional)
+-- @return      the extra config value
+--
 function _instance:extraconf(name, item, key)
     return self._INFO:extraconf(name, item, key)
 end
@@ -112,6 +130,9 @@ function _instance:extraconf_set(name, item, key, value)
 end
 
 -- get the rule name
+--
+-- @return      the rule name string
+--
 function _instance:name()
     return self._NAME
 end
@@ -171,7 +192,12 @@ function _instance:orderdeps()
     return self._ORDERDEPS
 end
 
--- get xxx_script
+-- get the rule script function (on_build, on_install, etc.)
+--
+-- @param name     the script name, e.g. "build", "install", "clean"
+-- @param generic  use generic script if platform-specific not found?
+-- @return         the script function
+--
 function _instance:script(name, generic)
 
     -- get script