improve comments

1 files changed, 48 insertions, 5 deletions

diff --git a/xmake/core/base/hash.lua b/xmake/core/base/hash.lua
index d08a7d93b..4b37946e8 100644
--- a/xmake/core/base/hash.lua
+++ b/xmake/core/base/hash.lua
@@ -35,7 +35,11 @@ hash._rand32 = hash._rand32 or hash.rand32
 hash._rand64 = hash._rand64 or hash.rand64
 hash._rand128 = hash._rand128 or hash.rand128
 
--- generate md5 from the given file or data
+-- generate md5 hash from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.md5(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -48,7 +52,11 @@ function hash.md5(file_or_data)
     return hashstr, errors
 end
 
--- generate sha1 from the given file or data
+-- generate sha1 hash from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.sha1(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -61,7 +69,11 @@ function hash.sha1(file_or_data)
     return hashstr, errors
 end
 
--- generate sha256 from the given file or data
+-- generate sha256 hash from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.sha256(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -75,11 +87,19 @@ function hash.sha256(file_or_data)
 end
 
 -- generate uuid, e.g "91E8ECF1-417F-4EDF-A574-E22D7D8D204A"
+--
+-- @param str   the seed string (optional, random if nil)
+-- @return      the uuid string
+--
 function hash.uuid(str)
     return hash.uuid4(str)
 end
 
 -- generate xxhash32 from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.xxhash32(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -93,6 +113,10 @@ function hash.xxhash32(file_or_data)
 end
 
 -- generate xxhash64 from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.xxhash64(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -106,6 +130,10 @@ function hash.xxhash64(file_or_data)
 end
 
 -- generate xxhash128 from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.xxhash128(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -119,6 +147,10 @@ function hash.xxhash128(file_or_data)
 end
 
 -- generate hash32 from string, e.g. "91e8ecf1"
+--
+-- @param str   the input string
+-- @return      the 32-bit hash hex string
+--
 function hash.strhash32(str)
     if hash._rand32 then
         local data = libc.ptraddr(libc.dataptr(str))
@@ -131,6 +163,10 @@ function hash.strhash32(str)
 end
 
 -- generate hash64 from string, e.g. "91e8ecf191e8ecf1"
+--
+-- @param str   the input string
+-- @return      the 64-bit hash hex string
+--
 function hash.strhash64(str)
     local data = libc.ptraddr(libc.dataptr(str))
     local size = #str
@@ -138,14 +174,21 @@ function hash.strhash64(str)
 end
 
 -- generate hash128 from string, e.g. "91e8ecf1417f4edfa574e22d7d8d204a"
+--
+-- @param str   the input string
+-- @return      the 128-bit hash hex string
+--
 function hash.strhash128(str)
     local data = libc.ptraddr(libc.dataptr(str))
     local size = #str
     return hash._xxhash(128, data, size)
 end
 
--- generate random32 hash
--- @note it is easy to trigger hash conflicts
+-- generate random 32-bit hash
+--
+-- @return      the random hash hex string
+-- @note        it is easy to trigger hash conflicts
+--
 function hash.rand32()
     if hash._rand32 then
         return hash._rand32()