Improve c2man Documented-Total count. Changes:

- add missing description - add missing returns section
2005-11-12 19:12:03 +00:00 · 2005-11-12 19:12:03 +00:00 · ec350525e3
parent 8ba040e157
commit ec350525e3
5 changed files with 90 additions and 5 deletions
--- a/dlls/advapi32/crypt.c
+++ b/dlls/advapi32/crypt.c
@ -1533,6 +1533,8 @@ BOOL WINAPI CryptHashData (HCRYPTHASH hHash, const BYTE *pbData, DWORD dwDataLen
 /******************************************************************************
 * CryptHashSessionKey (ADVAPI32.@)
 *
+ * Compute the cryptographic hash of a session key object.
+ *
 * PARAMS 
 *  hHash   [I] Handle to the hash object.
 *  hKey    [I] Handle to the key to be hashed.
@ -1563,6 +1565,8 @@ BOOL WINAPI CryptHashSessionKey (HCRYPTHASH hHash, HCRYPTKEY hKey, DWORD dwFlags
 /******************************************************************************
 * CryptImportKey (ADVAPI32.@)
 *
+ * Transfer a cryptographic key from a key BLOB into a cryptographic service provider (CSP).
+ *
 * PARAMS
 *  hProv     [I] Handle of a CSP.
 *  pbData    [I] Contains the key to be imported.
--- a/dlls/advapi32/crypt_sha.c
+++ b/dlls/advapi32/crypt_sha.c
@ -101,6 +101,12 @@ void SHA1Transform(ULONG State[5], UCHAR Buffer[64])
 * A_SHAInit [ADVAPI32.@]
 *
 * Initialize a SHA context structure.
+ *
+ * PARAMS
+ *  Context [O] SHA context
+ *
+ * RETURNS
+ *  Nothing
 */
 VOID WINAPI
 A_SHAInit(PSHA_CTX Context)
@ -119,6 +125,14 @@ A_SHAInit(PSHA_CTX Context)
 * A_SHAUpdate [ADVAPI32.@]
 *
 * Update a SHA context with a hashed data from supplied buffer.
+ *
+ * PARAMS
+ *  Context    [O] SHA context
+ *  Buffer     [I] hashed data
+ *  BufferSize [I] hashed data size
+ *
+ * RETURNS
+ *  Nothing
 */
 VOID WINAPI
 A_SHAUpdate(PSHA_CTX Context, PCHAR Buffer, UINT BufferSize)
@ -155,6 +169,13 @@ A_SHAUpdate(PSHA_CTX Context, PCHAR Buffer, UINT BufferSize)
 * A_SHAFinal [ADVAPI32.@]
 *
 * Finalize SHA context and return the resulting hash.
+ *
+ * PARAMS
+ *  Context [I/O] SHA context
+ *  Result  [O] resulting hash
+ *
+ * RETURNS
+ *  Nothing
 */
 VOID WINAPI
 A_SHAFinal(PSHA_CTX Context, PULONG Result)
--- a/dlls/advapi32/eventlog.c
+++ b/dlls/advapi32/eventlog.c
@ -442,6 +442,25 @@ BOOL WINAPI ReportEventW( HANDLE hEventLog, WORD wType, WORD wCategory, DWORD dw
 /******************************************************************************
 * RegisterTraceGuidsW [ADVAPI32.@]
 *
+ * Register an event trace provider and the event trace classes that it uses
+ * to generate events.
+ *
+ * PARAMS
+ *  RequestAddress     [I]   ControlCallback function
+ *  RequestContext     [I]   Optional provider-defined context
+ *  ControlGuid        [I]   GUID of the registering provider
+ *  GuidCount          [I]   Number of elements in the TraceGuidReg array
+ *  TraceGuidReg       [I/O] Array of TRACE_GUID_REGISTRATION structures
+ *  MofImagePath       [I]   not supported, set to NULL
+ *  MofResourceNmae    [I]   not supported, set to NULL
+ *  RegistrationHandle [O]   Provider's registration handle
+ *
+ * RETURNS
+ *  Success: ERROR_SUCCESS
+ *  Failure: System error code
+ *
+ * FIXME
+ *  Stub.
 */
 ULONG WINAPI RegisterTraceGuidsW( WMIDPREQUEST RequestAddress,
                PVOID RequestContext, LPCGUID ControlGuid, ULONG GuidCount,
@ -457,6 +476,10 @@ ULONG WINAPI RegisterTraceGuidsW( WMIDPREQUEST RequestAddress,
 /******************************************************************************
 * RegisterTraceGuidsA [ADVAPI32.@]
 *
+ * See RegisterTraceGuidsW.
+ *
+ * FIXME
+ *  Stub.
 */
 ULONG WINAPI RegisterTraceGuidsA( WMIDPREQUEST RequestAddress,
                PVOID RequestContext, LPCGUID ControlGuid, ULONG GuidCount,
--- a/dlls/advapi32/registry.c
+++ b/dlls/advapi32/registry.c
@ -380,11 +380,23 @@ DWORD WINAPI RegOpenKeyA( HKEY hkey, LPCSTR name, PHKEY retkey )

 /******************************************************************************
 * RegOpenCurrentUser   [ADVAPI32.@]
- * 
- * FIXME: This function is supposed to retrieve a handle to the
- * HKEY_CURRENT_USER for the user the current thread is impersonating.
- * Since Wine does not currently allow threads to impersonate other users,
- * this stub should work fine.
+ *
+ * Get a handle to the HKEY_CURRENT_USER key for the user 
+ * the current thread is impersonating.
+ *
+ * PARAMS
+ *  access [I] Desired access rights to the key
+ *  retkey [O] Handle to the opened key
+ *
+ * RETURNS
+ *  Success: ERROR_SUCCESS
+ *  Failure: nonzero error code from Winerror.h
+ *
+ * FIXME
+ *  This function is supposed to retrieve a handle to the
+ *  HKEY_CURRENT_USER for the user the current thread is impersonating.
+ *  Since Wine does not currently allow threads to impersonate other users,
+ *  this stub should work fine.
 */
 DWORD WINAPI RegOpenCurrentUser( REGSAM access, PHKEY retkey )
 {
@ -396,6 +408,8 @@ DWORD WINAPI RegOpenCurrentUser( REGSAM access, PHKEY retkey )
 /******************************************************************************
 * RegEnumKeyExW   [ADVAPI32.@]
 *
+ * Enumerate subkeys of the specified open registry key.
+ *
 * PARAMS
 *  hkey         [I] Handle to key to enumerate
 *  index        [I] Index of subkey to enumerate
@ -1837,6 +1851,9 @@ DWORD WINAPI RegDeleteValueA( HKEY hkey, LPCSTR name )
 /******************************************************************************
 * RegLoadKeyW   [ADVAPI32.@]
 *
+ * Create a subkey under HKEY_USERS or HKEY_LOCAL_MACHINE and store
+ * registration information from a specified file into that subkey.
+ *
 * PARAMS
 *  hkey      [I] Handle of open key
 *  subkey    [I] Address of name of subkey
@ -1900,6 +1917,8 @@ LONG WINAPI RegLoadKeyA( HKEY hkey, LPCSTR subkey, LPCSTR filename )
 /******************************************************************************
 * RegSaveKeyW   [ADVAPI32.@]
 *
+ * Save a key and all of its subkeys and values to a new file in the standard format.
+ *
 * PARAMS
 *  hkey   [I] Handle of key where save begins
 *  lpFile [I] Address of filename to save to
@ -1981,6 +2000,8 @@ LONG WINAPI RegSaveKeyA( HKEY hkey, LPCSTR file, LPSECURITY_ATTRIBUTES sa )
 /******************************************************************************
 * RegRestoreKeyW [ADVAPI32.@]
 *
+ * Read the registry information from a file and copy it over a key.
+ *
 * PARAMS
 *  hkey    [I] Handle of key where restore begins
 *  lpFile  [I] Address of filename containing saved tree
@ -2026,6 +2047,8 @@ LONG WINAPI RegRestoreKeyA( HKEY hkey, LPCSTR lpFile, DWORD dwFlags )
 /******************************************************************************
 * RegUnLoadKeyW [ADVAPI32.@]
 *
+ * Unload a registry key and its subkeys from the registry.
+ *
 * PARAMS
 *  hkey     [I] Handle of open key
 *  lpSubKey [I] Address of name of subkey to unload
@ -2073,6 +2096,8 @@ LONG WINAPI RegUnLoadKeyA( HKEY hkey, LPCSTR lpSubKey )
 /******************************************************************************
 * RegReplaceKeyW [ADVAPI32.@]
 *
+ * Replace the file backing a registry key and all its subkeys with another file.
+ *
 * PARAMS
 *  hkey      [I] Handle of open key
 *  lpSubKey  [I] Address of name of subkey
@ -2119,6 +2144,8 @@ LONG WINAPI RegReplaceKeyA( HKEY hkey, LPCSTR lpSubKey, LPCSTR lpNewFile,
 /******************************************************************************
 * RegSetKeySecurity [ADVAPI32.@]
 *
+ * Set the security of an open registry key.
+ *
 * PARAMS
 *  hkey          [I] Open handle of key to set
 *  SecurityInfo  [I] Descriptor contents
@ -2212,6 +2239,8 @@ DWORD WINAPI RegFlushKey( HKEY hkey )
 /******************************************************************************
 * RegConnectRegistryW [ADVAPI32.@]
 *
+ * Establishe a connection to a predefined registry key on another computer.
+ *
 * PARAMS
 *  lpMachineName [I] Address of name of remote computer
 *  hHey          [I] Predefined registry handle
@ -2276,6 +2305,8 @@ LONG WINAPI RegConnectRegistryA( LPCSTR machine, HKEY hkey, PHKEY reskey )
 /******************************************************************************
 * RegNotifyChangeKeyValue [ADVAPI32.@]
 *
+ * Notify the caller about changes to the attributes or contents of a registry key.
+ *
 * PARAMS
 *  hkey            [I] Handle of key to watch
 *  fWatchSubTree   [I] Flag for subkey notification
--- a/dlls/advapi32/security.c
+++ b/dlls/advapi32/security.c
@ -274,6 +274,8 @@ CheckTokenMembership( HANDLE TokenHandle, PSID SidToCheck,
 /******************************************************************************
 * GetTokenInformation [ADVAPI32.@]
 *
+ * Get a type of information about an access token.
+ *
 * PARAMS
 *   token           [I] Handle from OpenProcessToken() or OpenThreadToken()
 *   tokeninfoclass  [I] A TOKEN_INFORMATION_CLASS from "winnt.h"
@ -629,6 +631,10 @@ GetLengthSid (PSID pSid)
 *  pOldSD                [I]
 *  lpdwBufferLength      [I/O]
 *  pNewSD                [O]
+ *
+ * RETURNS
+ *  Success: ERROR_SUCCESS
+ *  Failure: nonzero error code from Winerror.h
 */
 DWORD WINAPI BuildSecurityDescriptorA(
    IN PTRUSTEE_A pOwner,