Zebediah Figura : ntdll: Add some documentation for ntdll_umbstowcs() and ntdll_wcstoumbs().

[Alexandre Julliard]

Module: wine
Branch: master
Commit: 88b77020f27b83d5c11eb425756a0dee20ad5f63
URL:    https://source.winehq.org/git/wine.git/?a=commit;h=88b77020f27b83d5c11eb4257...

Author: Zebediah Figura <zfigura(a)codeweavers.com>
Date:   Wed Jun 22 17:06:07 2022 -0500

ntdll: Add some documentation for ntdll_umbstowcs() and ntdll_wcstoumbs().

These functions do match e.g. mbstowcs() and MultiByteToWideChar(), but that
fact is not inherently obvious [and they don't match RtlMultiByteToUnicodeN(),
for example.]

---

 dlls/ntdll/unix/env.c | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/dlls/ntdll/unix/env.c b/dlls/ntdll/unix/env.c
index a71df03966f..f69e4e80f0d 100644
--- a/dlls/ntdll/unix/env.c
+++ b/dlls/ntdll/unix/env.c
@@ -364,6 +364,13 @@ static BOOL is_dynamic_env_var( const char *var )
 
 /******************************************************************
  *      ntdll_umbstowcs  (ntdll.so)
+ *
+ * Convert a multi-byte string in the Unix code page to UTF-16. Returns the
+ * number of characters converted, which may be less than the entire source
+ * string. The destination string must not be NULL.
+ *
+ * The size of the output buffer, and the return value, are both given in
+ * characters, not bytes.
  */
 DWORD ntdll_umbstowcs( const char *src, DWORD srclen, WCHAR *dst, DWORD dstlen )
 {
@@ -381,6 +388,11 @@ DWORD ntdll_umbstowcs( const char *src, DWORD srclen, WCHAR *dst, DWORD dstlen )
 
 /******************************************************************
  *      ntdll_wcstoumbs  (ntdll.so)
+ *
+ * Convert a UTF-16 string to a multi-byte string in the Unix code page.
+ * The destination string must not be NULL.
+ *
+ * The size of the source string is given in characters, not bytes.
  */
 int ntdll_wcstoumbs( const WCHAR *src, DWORD srclen, char *dst, DWORD dstlen, BOOL strict )
 {