Improve c2man Documented-Total count.

dlls/advapi32/advapi.c

@@ -144,6 +144,9 @@ BOOL WINAPI GetCurrentHwProfileW(LPHW_PROFILE_INFOW pInfo)
  *  buf   [I] Text buffer to test
  *  len   [I] Length of buf
  *  flags [O] Destination for test results
+ *
+ * RETURNS
+ *  TRUE if the buffer is likely Unicode, FALSE otherwise.
  */
 BOOL WINAPI IsTextUnicode( LPCVOID buf, INT len, LPINT flags )
 {
@@ -220,7 +223,7 @@ BOOL WINAPI InitiateSystemShutdownExA( LPSTR lpMachineName, LPSTR lpMessage,
 /******************************************************************************
  * InitiateSystemShutdownExW [ADVAPI32.@]
  *
- * see InitiateSystemShutdownExA
+ * See InitiateSystemShutdownExA.
  */
 BOOL WINAPI InitiateSystemShutdownExW( LPWSTR lpMachineName, LPWSTR lpMessage,
          DWORD dwTimeout, BOOL bForceAppsClosed, BOOL bRebootAfterShutdown,

dlls/advapi32/crypt.c

@@ -269,16 +269,18 @@ error:
 
 /******************************************************************************
  * CryptAcquireContextW (ADVAPI32.@)
+ *
  * Acquire a crypto provider context handle.
  *
  * PARAMS
- * phProv: Pointer to HCRYPTPROV for the output.
+ *  phProv       [O] Pointer to HCRYPTPROV for the output.
- * pszContainer: Key Container Name
+ *  pszContainer [I] Key Container Name
- * pszProvider: Cryptographic Service Provider Name
+ *  pszProvider  [I] Cryptographic Service Provider Name
- * dwProvType: Crypto provider type to get a handle.
+ *  dwProvType   [I] Crypto provider type to get a handle.
- * dwFlags: flags for the operation
+ *  dwFlags      [I] flags for the operation
  *
- * RETURNS TRUE on success, FALSE on failure.
+ * RETURNS 
+ *  TRUE on success, FALSE on failure.
  */
 BOOL WINAPI CryptAcquireContextW (HCRYPTPROV *phProv, LPCWSTR pszContainer,
 		LPCWSTR pszProvider, DWORD dwProvType, DWORD dwFlags)
@@ -493,7 +495,7 @@ error:
 /******************************************************************************
  * CryptAcquireContextA (ADVAPI32.@)
  *
- * see CryptAcquireContextW
+ * See CryptAcquireContextW.
  */
 BOOL WINAPI CryptAcquireContextA (HCRYPTPROV *phProv, LPCSTR pszContainer,
 		LPCSTR pszProvider, DWORD dwProvType, DWORD dwFlags)
@@ -1052,7 +1054,7 @@ BOOL WINAPI CryptEnumProvidersW (DWORD dwIndex, DWORD *pdwReserved,
 /******************************************************************************
  * CryptEnumProvidersA (ADVAPI32.@)
  *
- * see CryptEnumProvidersW
+ * See CryptEnumProvidersW.
  */
 BOOL WINAPI CryptEnumProvidersA (DWORD dwIndex, DWORD *pdwReserved,
 		DWORD dwFlags, DWORD *pdwProvType, LPSTR pszProvName, DWORD *pcbProvName)
@@ -1081,7 +1083,7 @@ BOOL WINAPI CryptEnumProvidersA (DWORD dwIndex, DWORD *pdwReserved,
 }
 
 /******************************************************************************
- * CryptEnumProviderTypesW (ADVAPI32i.@)
+ * CryptEnumProviderTypesW (ADVAPI32.@)
  *
  * Retrieves the next type of CSP supported.
  *
@@ -1158,7 +1160,7 @@ BOOL WINAPI CryptEnumProviderTypesW (DWORD dwIndex, DWORD *pdwReserved,
 /******************************************************************************
  * CryptEnumProviderTypesA (ADVAPI32.@)
  *
- * see CryptEnumProviderTypesW
+ * See CryptEnumProviderTypesW.
  */
 BOOL WINAPI CryptEnumProviderTypesA (DWORD dwIndex, DWORD *pdwReserved,
 		DWORD dwFlags, DWORD *pdwProvType, LPSTR pszTypeName, DWORD *pcbTypeName)
@@ -1326,7 +1328,7 @@ BOOL WINAPI CryptGetDefaultProviderW (DWORD dwProvType, DWORD *pdwReserved,
 /******************************************************************************
  * CryptGetDefaultProviderA (ADVAPI32.@)
  *
- * see CryptGetDefaultProviderW
+ * See CryptGetDefaultProviderW.
  */
 BOOL WINAPI CryptGetDefaultProviderA (DWORD dwProvType, DWORD *pdwReserved,
 		DWORD dwFlags, LPSTR pszProvName, DWORD *pcbProvName)
@@ -1643,7 +1645,7 @@ BOOL WINAPI CryptSignHashW (HCRYPTHASH hHash, DWORD dwKeySpec, LPCWSTR sDescript
 /******************************************************************************
  * CryptSignHashA (ADVAPI32.@)
  *
- * ASCII version of CryptSignHashW
+ * See CryptSignHashW.
  */
 BOOL WINAPI CryptSignHashA (HCRYPTHASH hHash, DWORD dwKeySpec, LPCSTR sDescription,
 		DWORD dwFlags, BYTE *pbSignature, DWORD *pdwSigLen)
@@ -1743,7 +1745,7 @@ BOOL WINAPI CryptSetProviderA (LPCSTR pszProvName, DWORD dwProvType)
 /******************************************************************************
  * CryptSetProviderW (ADVAPI32.@)
  *
- * See CryptSetProviderA
+ * See CryptSetProviderA.
  */
 BOOL WINAPI CryptSetProviderW (LPCWSTR pszProvName, DWORD dwProvType)
 {
@@ -1829,7 +1831,7 @@ BOOL WINAPI CryptSetProviderExW (LPCWSTR pszProvName, DWORD dwProvType, DWORD *p
 /******************************************************************************
  * CryptSetProviderExA (ADVAPI32.@)
  *
- * See CryptSetProviderExW
+ * See CryptSetProviderExW.
  */
 BOOL WINAPI CryptSetProviderExA (LPCSTR pszProvName, DWORD dwProvType, DWORD *pdwReserved, DWORD dwFlags)
 {
@@ -1941,7 +1943,7 @@ BOOL WINAPI CryptVerifySignatureW (HCRYPTHASH hHash, BYTE *pbSignature, DWORD dw
 /******************************************************************************
  * CryptVerifySignatureA (ADVAPI32.@)
  *
- * ASCII version of CryptVerifySignatureW
+ * See CryptVerifySignatureW.
  */
 BOOL WINAPI CryptVerifySignatureA (HCRYPTHASH hHash, BYTE *pbSignature, DWORD dwSigLen,
 		HCRYPTKEY hPubKey, LPCSTR sDescription, DWORD dwFlags)
@@ -1967,6 +1969,10 @@ BOOL WINAPI CryptVerifySignatureA (HCRYPTHASH hHash, BYTE *pbSignature, DWORD dw
  * PARAMS
  *  pbBufer [O] Pointer to memory to receive random bytes.
  *  dwLen   [I] Number of random bytes to fetch.
+ *
+ * RETURNS
+ *  Success: TRUE
+ *  Failure: FALSE
  */
 
 BOOL WINAPI SystemFunction036(PVOID pbBuffer, ULONG dwLen)
@@ -2010,6 +2016,10 @@ BOOL WINAPI SystemFunction036(PVOID pbBuffer, ULONG dwLen)
  *    RTL_ENCRYPT_OPTION_CROSS_PROCESS 
  *    RTL_ENCRYPT_OPTION_SAME_LOGON
  *    
+ * RETURNS
+ *  Success: STATUS_SUCCESS
+ *  Failure: NTSTATUS error code
+ *
  * NOTES
  *  length must be a multiple of RTL_ENCRYPT_MEMORY_SIZE.
  *  If flags are specified when encrypting, the same flag value must be given
@@ -2034,6 +2044,10 @@ NTSTATUS WINAPI SystemFunction040(PVOID memory, ULONG length, ULONG flags)
  *    RTL_ENCRYPT_OPTION_CROSS_PROCESS
  *    RTL_ENCRYPT_OPTION_SAME_LOGON
  *
+ * RETURNS
+ *  Success: STATUS_SUCCESS
+ *  Failure: NTSTATUS error code
+ *
  * NOTES
  *  length must be a multiple of RTL_ENCRYPT_MEMORY_SIZE.
  *  If flags are specified when encrypting, the same flag value must be given

dlls/advapi32/eventlog.c

@@ -58,7 +58,7 @@ BOOL WINAPI BackupEventLogA( HANDLE hEventLog, LPCSTR lpBackupFileName )
 /******************************************************************************
  * BackupEventLogW [ADVAPI32.@]
  *
- * see BackupEventLogA
+ * See BackupEventLogA.
  */
 BOOL WINAPI BackupEventLogW( HANDLE hEventLog, LPCWSTR lpBackupFileName )
 {
@@ -90,7 +90,7 @@ BOOL WINAPI ClearEventLogA( HANDLE hEventLog, LPCSTR lpBackupFileName )
 /******************************************************************************
  * ClearEventLogW [ADVAPI32.@]
  *
- * see ClearEventLogA
+ * See ClearEventLogA.
  */
 BOOL WINAPI ClearEventLogW( HANDLE hEventLog, LPCWSTR lpBackupFileName )
 {
@@ -225,7 +225,7 @@ HANDLE WINAPI OpenBackupEventLogA( LPCSTR lpUNCServerName, LPCSTR lpFileName )
 /******************************************************************************
  * OpenBackupEventLogW [ADVAPI32.@]
  *
- * see OpenBackupEventLogA
+ * See OpenBackupEventLogA.
  */
 HANDLE WINAPI OpenBackupEventLogW( LPCWSTR lpUNCServerName, LPCWSTR lpFileName )
 {
@@ -256,7 +256,7 @@ HANDLE WINAPI OpenEventLogA( LPCSTR uncname, LPCSTR source )
 /******************************************************************************
  * OpenEventLogW [ADVAPI32.@]
  *
- * see OpenEventLogA
+ * See OpenEventLogA.
  */
 HANDLE WINAPI OpenEventLogW( LPCWSTR uncname, LPCWSTR source )
 {
@@ -294,7 +294,7 @@ BOOL WINAPI ReadEventLogA( HANDLE hEventLog, DWORD dwReadFlags, DWORD dwRecordOf
 /******************************************************************************
  * ReadEventLogW [ADVAPI32.@]
  *
- * see ReadEventLogA
+ * See ReadEventLogA.
  */
 BOOL WINAPI ReadEventLogW( HANDLE hEventLog, DWORD dwReadFlags, DWORD dwRecordOffset,
     LPVOID lpBuffer, DWORD nNumberOfBytesToRead, DWORD *pnBytesRead, DWORD *pnMinNumberOfBytesNeeded )
@@ -337,7 +337,7 @@ HANDLE WINAPI RegisterEventSourceA( LPCSTR lpUNCServerName, LPCSTR lpSourceName
 /******************************************************************************
  * RegisterEventSourceW [ADVAPI32.@]
  *
- * see RegisterEventSourceA
+ * See RegisterEventSourceA.
  */
 HANDLE WINAPI RegisterEventSourceW( LPCWSTR lpUNCServerName, LPCWSTR lpSourceName )
 {
@@ -403,7 +403,7 @@ BOOL WINAPI ReportEventA ( HANDLE hEventLog, WORD wType, WORD wCategory, DWORD d
 /******************************************************************************
  * ReportEventW [ADVAPI32.@]
  *
- * see ReportEventA
+ * See ReportEventA.
  */
 BOOL WINAPI ReportEventW( HANDLE hEventLog, WORD wType, WORD wCategory, DWORD dwEventID,
     PSID lpUserSid, WORD wNumStrings, DWORD dwDataSize, LPCWSTR *lpStrings, LPVOID lpRawData )

dlls/advapi32/registry.c

@@ -257,7 +257,7 @@ DWORD WINAPI RegCreateKeyW( HKEY hkey, LPCWSTR lpSubKey, PHKEY phkResult )
 /******************************************************************************
  * RegCreateKeyA   [ADVAPI32.@]
  *
- * see RegCreateKeyW
+ * See RegCreateKeyW.
  */
 DWORD WINAPI RegCreateKeyA( HKEY hkey, LPCSTR lpSubKey, PHKEY phkResult )
 {
@@ -473,7 +473,7 @@ DWORD WINAPI RegEnumKeyExW( HKEY hkey, DWORD index, LPWSTR name, LPDWORD name_le
 /******************************************************************************
  * RegEnumKeyExA   [ADVAPI32.@]
  *
- * see RegEnumKeyExW
+ * See RegEnumKeyExW.
  */
 DWORD WINAPI RegEnumKeyExA( HKEY hkey, DWORD index, LPSTR name, LPDWORD name_len,
                             LPDWORD reserved, LPSTR class, LPDWORD class_len, FILETIME *ft )
@@ -563,7 +563,7 @@ DWORD WINAPI RegEnumKeyW( HKEY hkey, DWORD index, LPWSTR name, DWORD name_len )
 /******************************************************************************
  * RegEnumKeyA   [ADVAPI32.@]
  *
- * see RegEnumKeyW
+ * See RegEnumKeyW.
  */
 DWORD WINAPI RegEnumKeyA( HKEY hkey, DWORD index, LPSTR name, DWORD name_len )
 {
@@ -574,6 +574,8 @@ DWORD WINAPI RegEnumKeyA( HKEY hkey, DWORD index, LPSTR name, DWORD name_len )
 /******************************************************************************
  * RegQueryInfoKeyW   [ADVAPI32.@]
  *
+ * Retrieves information about the specified registry key.
+ *
  * PARAMS
  *    hkey       [I] Handle to key to query
  *    class      [O] Buffer for class string
@@ -588,10 +590,15 @@ DWORD WINAPI RegEnumKeyA( HKEY hkey, DWORD index, LPSTR name, DWORD name_len )
  *    security   [O] Buffer for security descriptor length
  *    modif      [O] Modification time
  *
- * - win95 allows class to be valid and class_len to be NULL
+ * RETURNS
- * - winnt returns ERROR_INVALID_PARAMETER if class is valid and class_len is NULL
+ *  Success: ERROR_SUCCESS
- * - both allow class to be NULL and class_len to be NULL
+ *  Failure: system error code.
- * (it's hard to test validity, so test !NULL instead)
+ *
+ * NOTES
+ *  - win95 allows class to be valid and class_len to be NULL
+ *  - winnt returns ERROR_INVALID_PARAMETER if class is valid and class_len is NULL
+ *  - both allow class to be NULL and class_len to be NULL
+ *    (it's hard to test validity, so test !NULL instead)
  */
 DWORD WINAPI RegQueryInfoKeyW( HKEY hkey, LPWSTR class, LPDWORD class_len, LPDWORD reserved,
                                LPDWORD subkeys, LPDWORD max_subkey, LPDWORD max_class,
@@ -714,7 +721,7 @@ DWORD WINAPI RegQueryMultipleValuesA(HKEY hkey, PVALENTA val_list, DWORD num_val
 /******************************************************************************
  * RegQueryMultipleValuesW   [ADVAPI32.@]
  *
- * see RegQueryMultipleValuesA
+ * See RegQueryMultipleValuesA.
  */
 DWORD WINAPI RegQueryMultipleValuesW(HKEY hkey, PVALENTW val_list, DWORD num_vals,
                                      LPWSTR lpValueBuf, LPDWORD ldwTotsize)
@@ -973,7 +980,7 @@ DWORD WINAPI RegSetValueExW( HKEY hkey, LPCWSTR name, DWORD reserved,
 /******************************************************************************
  * RegSetValueExA   [ADVAPI32.@]
  *
- * see RegSetValueExW
+ * See RegSetValueExW.
  *
  * NOTES
  *  win95 does not care about count for REG_SZ and finds out the len by itself (js)
@@ -1063,7 +1070,7 @@ DWORD WINAPI RegSetValueW( HKEY hkey, LPCWSTR name, DWORD type, LPCWSTR data, DW
 /******************************************************************************
  * RegSetValueA   [ADVAPI32.@]
  *
- * see RegSetValueW
+ * See RegSetValueW.
  */
 DWORD WINAPI RegSetValueA( HKEY hkey, LPCSTR name, DWORD type, LPCSTR data, DWORD count )
 {
@@ -1301,7 +1308,7 @@ DWORD WINAPI RegQueryValueW( HKEY hkey, LPCWSTR name, LPWSTR data, LPLONG count
 /******************************************************************************
  * RegQueryValueA   [ADVAPI32.@]
  *
- * see RegQueryValueW
+ * See RegQueryValueW.
  */
 DWORD WINAPI RegQueryValueA( HKEY hkey, LPCSTR name, LPSTR data, LPLONG count )
 {
@@ -1580,6 +1587,8 @@ LONG WINAPI RegGetValueA( HKEY hKey, LPCSTR pszSubKey, LPCSTR pszValue,
 /******************************************************************************
  * RegEnumValueW   [ADVAPI32.@]
  *
+ * Enumerates the values for the specified open registry key.
+ *
  * PARAMS
  *  hkey       [I] Handle to key to query
  *  index      [I] Index of value to query
@@ -1678,7 +1687,7 @@ DWORD WINAPI RegEnumValueW( HKEY hkey, DWORD index, LPWSTR value, LPDWORD val_co
 /******************************************************************************
  * RegEnumValueA   [ADVAPI32.@]
  *
- * see RegEnumValueW
+ * See RegEnumValueW.
  */
 DWORD WINAPI RegEnumValueA( HKEY hkey, DWORD index, LPSTR value, LPDWORD val_count,
                             LPDWORD reserved, LPDWORD type, LPBYTE data, LPDWORD count )
@@ -1867,7 +1876,7 @@ LONG WINAPI RegLoadKeyW( HKEY hkey, LPCWSTR subkey, LPCWSTR filename )
 /******************************************************************************
  * RegLoadKeyA   [ADVAPI32.@]
  *
- * see RegLoadKeyW
+ * See RegLoadKeyW.
  */
 LONG WINAPI RegLoadKeyA( HKEY hkey, LPCSTR subkey, LPCSTR filename )
 {
@@ -1954,7 +1963,7 @@ done:
 /******************************************************************************
  * RegSaveKeyA  [ADVAPI32.@]
  *
- * see RegSaveKeyW
+ * See RegSaveKeyW.
  */
 LONG WINAPI RegSaveKeyA( HKEY hkey, LPCSTR file, LPSECURITY_ATTRIBUTES sa )
 {
@@ -2000,7 +2009,7 @@ LONG WINAPI RegRestoreKeyW( HKEY hkey, LPCWSTR lpFile, DWORD dwFlags )
 /******************************************************************************
  * RegRestoreKeyA [ADVAPI32.@]
  *
- * see RegRestoreKeyW
+ * See RegRestoreKeyW.
  */
 LONG WINAPI RegRestoreKeyA( HKEY hkey, LPCSTR lpFile, DWORD dwFlags )
 {
@@ -2047,7 +2056,7 @@ LONG WINAPI RegUnLoadKeyW( HKEY hkey, LPCWSTR lpSubKey )
 /******************************************************************************
  * RegUnLoadKeyA [ADVAPI32.@]
  *
- * see RegUnLoadKeyW
+ * See RegUnLoadKeyW.
  */
 LONG WINAPI RegUnLoadKeyA( HKEY hkey, LPCSTR lpSubKey )
 {
@@ -2086,7 +2095,7 @@ LONG WINAPI RegReplaceKeyW( HKEY hkey, LPCWSTR lpSubKey, LPCWSTR lpNewFile,
 /******************************************************************************
  * RegReplaceKeyA [ADVAPI32.@]
  *
- * see RegReplaceKeyW
+ * See RegReplaceKeyW.
  */
 LONG WINAPI RegReplaceKeyA( HKEY hkey, LPCSTR lpSubKey, LPCSTR lpNewFile,
                               LPCSTR lpOldFile )
@@ -2250,7 +2259,7 @@ LONG WINAPI RegConnectRegistryW( LPCWSTR lpMachineName, HKEY hKey,
 /******************************************************************************
  * RegConnectRegistryA [ADVAPI32.@]
  *
- * see RegConnectRegistryW
+ * See RegConnectRegistryW.
  */
 LONG WINAPI RegConnectRegistryA( LPCSTR machine, HKEY hkey, PHKEY reskey )
 {

dlls/advapi32/security.c

@@ -1222,7 +1222,7 @@ BOOL WINAPI LookupPrivilegeDisplayNameW( LPCWSTR lpSystemName, LPCWSTR lpName, L
 /******************************************************************************
  * LookupPrivilegeNameA			[ADVAPI32.@]
  *
- * See LookupPrivilegeNameW
+ * See LookupPrivilegeNameW.
  */
 BOOL WINAPI
 LookupPrivilegeNameA( LPCSTR lpSystemName, PLUID lpLuid, LPSTR lpName,
@@ -1526,7 +1526,8 @@ LookupAccountSidW(
 
 /******************************************************************************
  * SetFileSecurityA [ADVAPI32.@]
- * Sets the security of a file or directory
+ *
+ * See SetFileSecurityW.
  */
 BOOL WINAPI SetFileSecurityA( LPCSTR lpFileName,
                                 SECURITY_INFORMATION RequestedInformation,
@@ -1551,12 +1552,17 @@ BOOL WINAPI SetFileSecurityA( LPCSTR lpFileName,
 
 /******************************************************************************
  * SetFileSecurityW [ADVAPI32.@]
- * Sets the security of a file or directory
+ *
+ * Sets the security of a file or directory.
  *
  * PARAMS
  *   lpFileName           []
  *   RequestedInformation []
  *   pSecurityDescriptor  []
+ *
+ * RETURNS
+ *  Success: TRUE.
+ *  Failure: FALSE.
  */
 BOOL WINAPI
 SetFileSecurityW( LPCWSTR lpFileName,

dlls/advapi32/service.c

@@ -731,11 +731,7 @@ static BOOL service_run_threads(void)
 /******************************************************************************
  * StartServiceCtrlDispatcherA [ADVAPI32.@]
  *
- *  Connects a process containing one or more services to the service control
+ * See StartServiceCtrlDispatcherW.
- * manager.
- *
- * PARAMS
- *   servent [I]  A list of the service names and service procedures
  */
 BOOL WINAPI StartServiceCtrlDispatcherA( LPSERVICE_TABLE_ENTRYA servent )
 {
@@ -778,6 +774,10 @@ BOOL WINAPI StartServiceCtrlDispatcherA( LPSERVICE_TABLE_ENTRYA servent )
  *
  * PARAMS
  *   servent [I]  A list of the service names and service procedures
+ *
+ * RETURNS
+ *  Success: TRUE.
+ *  Failure: FALSE.
  */
 BOOL WINAPI StartServiceCtrlDispatcherW( LPSERVICE_TABLE_ENTRYW servent )
 {